Use the Saagie GraphQL API

This documentation introduces basic usages of the Saagie GraphQL API with command line or GraphiQL.

1. What is GraphQL?

GraphQL is a query language for APIs that allows clients to request exactly the data they need, allowing them to get all the required data in a limited number of requests.

The GraphQL data (fields) can be described in the form of types, allowing clients to use client-side GraphQL libraries to consume the API and avoid manual parsing.

Since there are no fixed endpoints and data model, new abilities can be added to the API without creating breaking changes. This allows us to have a versionless API, as described in the GraphQL documentation.

A GraphQL operation can be either a read or a write operation: a GraphQL query is used to read or fetch values while a mutation is used to write or post values.
GraphQL queries help to reduce over fetching of data. This means smaller queries and less network traffic, which reduces response time.

The examples documented here can be run using:

The command line
GraphiQL

2. The command line

You can run GraphQL queries in a curl request on the command line on your local computer.

A GraphQL request can be made as a POST request to /api/graphql with the query as the payload.

2.1. Get your token

To generate your token and save it in a variable do as follows:

YOUR_TOKEN=$(curl -k -X "POST" -H "Content-Type: application/json" -H "Saagie-Realm: YOUR_REALM" "https://<your_saagie_host>/authentication/api/open/authenticate" -d '{"login":"LOGIN", "password":"PASSWORD"}')

2.2. Endpoint servers

To manage items related to the Projects module, such as projects, pipelines, jobs, and apps, use the Projects endpoint:

https://<your_saagie_host>/projects/api/platform/<your_platform_id>/graphql

To manage items related to the Catalog module, such as repositories, technologies, and contexts, use the Technology Catalog endpoint:

https://<your_saagie_host>/gateway/api/graphql

2.3. Query example

Here is an example of a query to retrieve all the projects ID and name:

curl -g -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" -d '{"query":"query{projects {id, name}}"}' https://<your_saagie_host>/projects/api/platform/<your_platform_id>/graphql

2.4. Mutation example

Here is an example of a mutation to run a job:

curl -g -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN" -d '{"query":"mutation($jobId:UUID!){runJob(jobId:$jobId){id}}", "variables" : "{\"jobId\" : \"<job-id>\"}"}' https://<your_saagie_host>/projects/api/platform/<your_platform_id>/graphql

3. GraphiQL

GraphiQL allows you to run queries and mutations directly against the server endpoint with syntax highlighting and autocomplete. It also allows you to explore the schema and types.

3.1. Authentication

To authenticate with the Saagie API, log in to https://<your_saagie_host> and enter the Saagie GraphiQL explorer URL in the same browser.

3.2. Saagie GraphiQL explorers

Once logged on your Saagie platform, use our interactive GraphiQL explorer to manage:

Your Projects:

https://<your_saagie_host>/projects/api/platform/<your_platform_id>/graphiql

Your Technology Catalog:

https://<your_saagie_host>/gateway/api/graphiql

3.3. Query examples

Queries are used to retrieve data.
Queries have:

Inputs, which can be arguments, such as which element you want to assign and to which object.
Return statements, that is, what you want to get in return when the request is successful.
Errors, which give you details on what went wrong.

Here is an example of a GraphQL query on the Projects API service to retrieve project IDs and names:

query{
  projects{
    id
    name
  }
}

The output should be similar to the following:

{
  "data": {
    "projects": [
      {
        "id": "your_project_id",
        "name": "your_project_name"
      }
    ]
  }
}

Here is an example of a GraphQL query on the Projects API service to retrieve job details from the project ID:

{
  jobs(projectId: "your_project_id") {
    id
    name
    technology {
      id
    }
  }
}

The output should be similar to the following:

{
  "data": {
    "jobs": [
      {
        "id": "your_job_id",
        "name": "your_job_name",
        "technology": {
          "id": "your_technology_id"
        }
      }
    ]
  }
}

3.4. Mutation examples

Mutations make changes to data. We can update, delete, or create new records.
It usually uses InputTypes and variables, which do not appear here.
Mutations have:

Inputs, which can be arguments, such as which element you want to assign and to which object.
Return statements, that is, what you want to get in return when the request is successful.
Errors, which give you details on what went wrong.

Run a job

Here is an example of a mutation on the Projects API service to run a job:

mutation {
  runJob(jobId: "your_job_id") {
    status
  }
}

Delete a job

Here is an example of a mutation on the Projects API service to delete a job:

mutation {
  deleteJob(jobId: "your_job_id")
}