GraphQL

The Ceres v2 UI makes backend API calls via a GraphQL layer. This page explains how to work with the GraphQL server.

The Source Code

The GraphQL codebase is comprised of two repositories:

• graphi-aws - This is a hapi.js plugin that exposes a GraphQL API. This plugin receives incoming GraphQL requests, translates them to AWS JavaScript SDK calls, and forwards them to the API Gateway.
• compute-spc-graphql - This is a hapi.js server that wraps the graphi-aws plugin. This server also provides logging, tracing, and Prometheus metrics reporting via Griffin.

Ensure that you have access to both of these repos before going any further.

Running the GraphQL Server Locally

• Clone the compute-spc-graphql repository.
• Install dependencies by running npm install.
• In the compute-spc-graphql root directory, create a file named .env. The contents of this file are shown below.
• Start the server by running npm run dev.

The contents of the .env file are:

PORT = 8080
NODE_ENV = production
AWS_ENDPOINT = https://apigw-dev.eu-lab-central-1.samsungspc.com
AWS_SECRET_ACCESS_KEY = SOME_AWS_SECRET_ACCESS_KEY
AWS_ACCESS_KEY_ID = SOME_AWS_ACCESS_KEY_ID
JAEGER_HOST = spcinfra-jaeger.spc.ecef0f.lab-eu.hermes
JAEGER_PORT = 6832
SPC_AUTHZ = true
SPC_AUTHZ_HEADER = X-Spc-Authorization
SPC_TRACE_HEADER = X-Spc-Client-Request-Id
SPC_TRACE_ID_HEADER = X-Spc-Trace-Id
OPENTRACING_HEADER = uber-trace-id
GRAYLOG_HOST = spcinfra-graylog.spc.ecef0f.lab-eu.hermes
GRAYLOG_PORT = 12201
GRAYLOG_SOURCE = SPC-GraphQL
TIER = development
REGION = lab-eu-1
PROMETHEUS_KEY = abc123

When starting the server locally, you may observe ENOTFOUND errors logged to the console. This is because your local .env file is not configured to communicate with Griffin. In general, this is fine because local development logs do not need to be sent to Griffin.

Integrating with the Ceres v2 UI

The top right corner of the UI contains a region selector. It will normally contain the text eu-lab-central-1. If you are running the UI in the DEV environment, this dropdown will also contain a localhost option. By selecting localhost, the UI will send its requests to the GraphQL server running at localhost:8080. This option is only available in the DEV environment. Note that the region selector is not visible if you are working with a global service such as IAM.

Local GraphQL Development

To make local changes to the GraphQL API, use the npm link command to make the compute-spc-graphql server reference your local copy of graphi-aws.

Adding/Modifying GraphQL APIs

In graphi-aws each API must be defined in the schema and have a resolver. An example schema file for the STS service is available here. The data types used in the GraphQL schema are taken from the corresponding AWS API documentation. For compatibility purposes, please deviate from the AWS documentation as little as possible.

The STS resolvers can be viewed here. If you do not deviate from the AWS API signatures, most of the GraphQL resolvers can be automatically generated, as seen in this file.