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