GraphQL for API endpoints#

Use GraphQL to query API endpoints via HTTP.

The Altair GraphQL IDE provides a flexible API interface used in place of REST API and Swagger, also known as OpenAPI. The interface consists of the following components:

A REST API is a framework for network-based software while GraphQL is a query language specification and tools interacting with a single endpoint via HTTP. When gathering data from a specific endpoint, REST API returns a full data set versus GraphQL that allows you to refine the data ranging from a number of objects to required fields in an entity. As a result of fetching the refined data, processing requirements are minimized while providing increased performance.

GraphQL addresses various limitations of Swagger including the return of specific data tailored to your requirements. In addition, GraphQL allows you to alias field names, explicitly separate reads from updates, also known as mutations, and receiving notifications updates upon occurrence. In GraphQL, notifications are called subscriptions.

To authenticate and access GraphQL IDE, perform the following:

  1. Create a User access key (UAK).
  2. In order to access the GraphQL IDE, you need to have a running instance of HCL™ Accelerate and navigate to the following URL:

    https://my_accelerate:port/graphiql

  3. In the upper left hand corner of the browser window, click set headers icon to set headers and authenticate with HCL Accelerate.

  4. In the Headers window, enter Authorization in the Header key field.
  5. In the Header value field, paste the user access key.
  6. Click the Save button.
  7. In the upper right hand corner of the browser window, click Docs and three column sections appear on the display. From left to right, the columns consist of the following sections:

    • Query
    • Response
    • Documentation

      Note: In the documentation section, there are the following operation types:

      Operation type Description
      Query Used by the client to request data on the server.
      Mutation Used to create new data and update and delete existing data.
      Subscription Used to create and support a connection to the server in real time. Subscriptions are event based.

      Note: Each of the aforementioned operation types are links and when you click any in the list, the available FIELDS associated with the types are displayed below.

  8. To search for an API endpoint and run a query, perform the following steps:

    • In the documentation section, enter the name of the endpoint in the Search docs field and press enter.
    • Locate and click the required endpoint.
    • Hover over the endpoint name and then click the ADD QUERY button to add the endpoint to the query section.
    • If required, add any parameters to the query.
    • Click either the Run query button in the query section or the Send Request button on the upper right hand corner of the browser window to run the query.
    • In the response section, the results of the query are displayed.

Uploading data to the API#

HCL Accelerate provides numerous plugins that you can use to integrate data into your releases and values streams. If a plugin is not available for your environment, or if you prefer to manage your own data integration, you can use an external client to upload data to REST API endpoints or GraphQL™. A tutorial that describes how to upload custom metrics is available.

The following examples use the Curl command line tool for typical POST use cases. You authorize requests with user access keys that you create in HCL Accelerate.

Note: Until new users are assigned to teams, they are automatically assigned to the Default team in the Viewer and Participant roles. Users in these roles can view objects, such as releases and value streams, but they cannot create or edit them. Additionally, users in these roles can generate user access tokens and access API endpoints with GET requests. Administrators grant users elevated permissions when they assign them to roles such as Lead Developer or Release Manager.

The following examples detail specific use cases for GraphQL endpoints when uploading custom data including:

Normalized metrics example#

The following example provides a Curl POST request that sends metrics data to the https://my_accelerate:port/api/v1/metrics endpoint.

You can define custom metric definitions and upload metric data using an external client, such as curl.

curl -X POST "https://localhost/api/v1/metrics" \
      -H "accept: application/json" \
      -H "Authorization: UserAccessKey my_access_key" \
      -H "Content-Type: application/json" \
      -k \
      -v \
      -d '{
            "tenantId": "5ade13625558f2c6688d15ce",
            "dataSet": "Tutorial data set",
            "record": {
              "metricDefinitionId": "AVG_BUILD_DURATION",
              "recordName": "My tutorial record",
              "pluginType": "plugin",
              "dataFormat": "custom",
              "executionDate": 1570028414997,
              "value": {
                "BuildDuration": 199
              },
              "description": "Tutorial data record"
            },
            "application": {
              "name": "Metric Tutorial"
            }
          }'

Note: The executionDate value must be a timestamp in milliseconds.

Metrics file upload example#

The following example provides a Curl POST request that uploads a file at the https://my_accelerate:port/api/v1/upload endpoint:

curl --request POST \
--url https://my_accelerate:port/api/v1/metrics/upload \
-H "Authorization: UserAccessKey my_access_key" \
-F file=@junit.xml \
-F 'payload={
"tenantId": "my_tenant_ID",
"dataSet": "Feb",
"application":
{ "name": "my App22" }

,
"environment": "Prod",
"record":
{ "metricDefinitionId": "Functional Tests", "pluginType": "junitXML", "dataFormat": "junitXML" }

}
' \
-k

Deployment data example#

The following example provides a Curl POST request that sends Jenkins deployment data to the https://my_accelerate:port/api/v1/deployments endpoint:

curl --request POST \
-H "Authorization: UserAccessKey my_access_key" \
-H 'content-type: application/json' \
-k --url https://my_accelerate:port/api/v1/deployments \
--data '{
"id_external": 8888,
"tenant_id": "my_tenant_ID",
"version_name": "1.2.3",
"version_id_external": "V1.2.3",
"result": "Succeeded",
"description" : "Application API Release Failed",
"by_user": "username",
"application":
{ "name": "cool-Jenkins-App" }

,
"start_time": "2019-02-02 00:10:58.856+00:00",
"end_time": "2019-02-02 00:12:58.856+00:00",
"type": "Jenkins",
"environment_id": "my_environmant_ID",
"environment_name": "QA"
}'

Build data example#

The following example provides a Curl POST request that sends build data to the https://my_accelerate:port/api/v1/builds endpoint:

curl -k --request POST \
--url https://my_accelerate/api/v1/builds \
-H "content-type: application/json" \
-H "Authorization: UserAccessKey my_access_key" \
--data '{
"id": "131",
"source": "Jenkins",
"tenantId": "my_tenant_ID",
"name": "IBM Build",
"status": "failure",
"application":
{ "name": "Accelerate SE" }

,
"url": "https:/12.34.20.45/job/VSE/master/5",
"number": 5,
"labels": ["Everything"],
"startTime": "2019-03-14 20:10:58.856+00:00",
"endTime": "2019-03-14 20:10:58.856+00:00",
"requestor": "admin"
}'

Parent topic: Extending product functions