id | title | sidebar_label | description | keywords | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
api |
Codiga GraphQL API - Introduction |
Introduction |
Everything you need to know about how to find and authenticate GraphQL on Codiga. |
|
:::info If you have any question about the API, please join our discord channel, we provide direct support on our channel. :::
:::info
Codiga API is completely implemented in GraphQL.
:::
GraphQL is a new way to interact between system. It exposes a typed API to the client that can structure his own query and decide exactly what data to query and receive.
There are many advantages for using GraphQL, such as query optimization but also a strong tool ecosystem and libraries in many languages. If you do not know GraphQL, we encourage you to learn more on graphql.org.
We have an accessible API to empower developers and let them develop new tools around our eco-system. By giving access to the data, we believe developers can extract the data they need and integrate the analysis data into their own development process (CI jobs, dashboard, etc.).
The API endpoint: https://api.codiga.io/graphql
. You submit POST
queries to this
API endpoint.
To query the API, you need to be authenticated. There are two ways to do this:
- API token: useful for programmatic access (such as CI jobs)
- JWT (Json Web Token): useful for frontend access (this is how app.codiga.io queries the API)
:::info
An API token is what you need if you want to start an integration with Codiga. It relies on tokens provided by the user.
:::
Go on the API tokens page and generate a new token. You can create multiple tokens and associate a description to them (for example, if you want to have one token for VS Code, one for your CI pipeline, etc.).
To access the API using the access and secret key, you need to specify two new headers:
X-Api-Token
: the token that has been generated for you.
The following command set the appropriate headers and get the list of all projects you own on Codiga.
curl -i -H 'Content-Type: application/json' \
-H "X-Api-Token: <YOUR-TOKEN>"
-X POST -d '{"query": "query {projects(howmany: 10, skip:0){name}}"}' \
https://api.codiga.io/graphql
When you use the API programmatically, make sure you set these headers when you send a GraphQL request.
:::warning
JWT are short-lived token, used for the web application at app.codiga.io. They are not recommended for any custom-integration. :::
A Json Web Token is a lightweight authentication mechanism that provide a token to authenticate within a given period of time.
The JWT authentication works in two passes:
- Generation of the token
- Use the API with the token
To generate the JWT, you need to invoke a mutation that will produce the token. The mutation will contain the real username and password of the user to authenticate.
mutation{
authentication(identifier:"<username>", password: "<password>"){
token
error
}
}
The mutation returns either the JWT (if the credentials are correct) or an error. This is the example of a successful authentication
{
"data": {
"authentication": {
"token": "eyJ1eXAiOiLKV1QPLCJhbGEiOiJIUzI1NiJ9.eyJleJAiOjE1FzkwNTk8NjUsKmlhqCI6MTU3ODk3MzM2NSwidXNlcklkIjogMn0.22AMf6y5Dyj3tzWVMw3eJPijkjS2sLOmt_O2VLvvafl",
"error": null
}
}
}
This is an example of a failed authentication attempt.
{
"data": {
"authentication": {
"token": null,
"error": "invalid-credentials"
}
}
}
To use the token, call the API as with any other library with an additional Authorization
header
that contains the value of your JWT.
GraphQL has a rich eco-system with multiple clients written in different languages. We show the use of such libraries for two languages: Python and Javascript.
There is a simple query example using the sgqlc client for Python. In the following code snippet, we authenticate using the couple of access and secret keys and print the username.
from sgqlc.endpoint.http import HTTPEndpoint
url = 'https://api.codiga.io/graphql'
headers = {
'X-Api-Token': '<your-token-here>'
}
query = '{user {username} }'
variables = {}
endpoint = HTTPEndpoint(url, headers)
data = endpoint(query, variables)
print(data.user.username)
The code below authenticates a user and get a JWT to send a request to the API to get the actual username
from sgqlc.endpoint.http import HTTPEndpoint
url = 'https://api.codiga.io/graphql'
# Getting the JWT first
query = '''
mutation{
authentication(identifier:"<USERNAME>", password: "PASSWORD"){
token
error
}
}
'''
variables = {}
endpoint = HTTPEndpoint(url)
data = endpoint(query, variables)
token = data['data']['authentication']['token']
# Querying with the JWT
query = '''
{
user {
username
}
}
'''
headers = {
'Authorization': token
}
endpoint = HTTPEndpoint(url, headers)
data = endpoint(query, variables)
print(data)
When a query or sub-query may potentially return a large number of results, the user has to specify two parameters to limit the number of results:
skip
: specify how many elements we skip before we start returning elements.howmany
: specify how many elements we want to return.
If the howmany
argument is too high, the query will be considered as too expensive and therefore, rejected.
These two argument can be used to implement pagination. For example, to show the first ten element of an object, you
will first call with skip
set to 0 and howmany
set to 10. To see the next 10 elements, you will set skip
to 10 and howmany
still to 10.