Saagie GraphQL API

This page presents the basic uses of the Saagie GraphQL API in command line and with GraphiQL.

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.

With the Command Line

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

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

Get Your Token

To generate your token and save it in a variable, enter the following command line:

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"}')

Endpoint Servers

Projects Module
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

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

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

Examples

Example 1. Query to retrieve all the project IDs and names

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

Example 2. 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

With 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.

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.

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>/technology/api/graphiql

Examples

Queries:
Queries are used to retrieve data and 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.

Example 3. 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"
      }
    ]
  }
}

Example 4. 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"
        }
      }
    ]
  }
}

Mutations:
Mutations are used to make changes to data (update, delete, or create new records) and 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.

Mutations usually use InputTypes and variables, which do not appear here.

Example 5. Mutation on the Projects API service to run a job

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

Example 6. Mutation on the Projects API service to delete a job

mutation {
  deleteJob(jobId: "your_job_id")
}