Our GraphQL API allows you to easily integrate OpsLevel with your other operational tools. You can enrich your internal tickets, incidents, and other systems with service and team data pulled from OpsLevel.
You can also use our API to automatically keep your OpsLevel info up-to-date by integrating it with real-time information pushed from tools like Terraform, Chef, Circle CI, etc. Historically, we’ve supported a YAML file integration with your git repositories for this same purpose, but our API now gives you more automation options.
What is GraphQL?
If you’ve used APIs before, you’ve probably encountered RESTful APIs. In REST, each resource generally has its own endpoint. For example, if OpsLevel had a REST API, there would be endpoints for services, teams, and users. If you wanted to fetch a list of all Services and their associated Teams, you would have to make many queries: one query to fetch the services, then one query per service to fetch the team for that service.
GraphQL works differently. GraphQL is a query language that lets clients declaratively specify what data they want to retrieve, not how it should be retrieved. With GraphQL, there is only one HTTP request that needs to be made and the response is completely customizable. GraphQL is also type safe, meaning your API client can verify that the data you’re asking for is sound. Visit the following link to see many other additional benefits of GraphQL over REST:
https://www.howtographql.com/basics/1-graphql-is-the-better-rest/
Why is OpsLevel using GraphQL for its API?
The data model for modern operations is incredibly rich and sophisticated. For example, there are dependencies between services themselves, between services and teams, teams and users, services and deployments, and deployments and infrastructure.
GraphQL is extremely well suited for clients to easily navigate this kind of rich data model. As discussed previously, GraphQL allows clients to fetch only the data they want and to do so in a single HTTP request. That leads to less bandwidth used (by only retrieving the necessary data) and less roundtrips (by not having to make a separate request per related resource).
Getting Started with the OpsLevel GraphQL API
Background
OpsLevel’s GraphQL API makes use of two high level types: queries and mutations.
Queries allow you to fetch information from OpsLevel.
Mutations allow you to push information to OpsLevel.
For more information on how to make GraphQL queries and mutations, visit https://graphql.org/learn/queries/.
The GraphiQL Explorer
The easiest way to get started with the the OpsLevel API is with GraphiQL, an interactive environment for exploring our API and its documentation.
This explorer will allow you to easily test queries and mutations before integrating our API with your app.
The GraphiQL Explorer consists of three main components:
- Query Editor pane
- Query Response pane
- Documentation Explorer
Query Editor
Where you will be writing your GraphQL queries.
Query Response Pane
Where you will see the responses to your GraphQL queries.
Documentation Explorer
GraphQL comes with first class support for documentation. You can interact with our API documentation directly from within GraphiQL.
Note: If you do not see the Documentation Explorer, it may be closed by default and can be opened by pressing the Docs button in the top right corner.
Executing GraphQL Queries from GraphiQL
You can execute your GraphQL queries from GraphiQL by pressing the Play button after writing your query in the Query Editor.
Sample Query
To get started, try pasting the following query in the Query Editor pane (the left pane of GraphiQL):
{
account {
name
}
}
Now press the Play button. You should see this result in the Query Response pane (the middle pane of GraphiQL):
{
"data": {
"account": {
"name": "Your Account Name"
}
}
}
Pagination
OpsLevel limits query results for an object to a maximum of 100 results. If you have more than 100 objects to fetch, you will have to paginate through the result set.
Objects whose name end with ConnectionType, such as ServiceConnectionType, are ones that you can paginate through. Please see GraphQL Pagination for an explanation of what these connection types are, how they relate to pagination, and code examples for how to paginate.
Returning data and errors on mutations
All OpsLevel GraphQL API mutations require you to return some payload. It is represented in the GraphQL Schema documentation by an exclamation mark (!) after the name of all mutations’ payloads.
For instance, in serviceCreate mutation, ServiceCreatePayload is required.
serviceCreate(input: ServiceCreateInput!): ServiceCreatePayload!
If you don’t include a return payload in your mutation, you will get an error. E.g.:
mutation {
tagDelete(input: { id:"Z2lkOi8vb3BzbGV2ZWwvVGFnLzU" })
}
Here is an example of how the mutation above should be correctly called.
mutation {
tagDelete(input: { id:"Z2lkOi8vb3BzbGV2ZWwvVGFnLzU" }) {
deletedTagId
errors {
message
}
}
}
Dealing with Errors
Always include the errors field in your mutations.
If you’re coming from the REST world, you might be expecting our API to return 4xxs for client errors. But in GraphQL, non-2xx errors only get returned for more serious issues like network failures. For client errors, we will return a 200, with more information about the error in the errors field. You should always include the errors field in your requests so that you can handle errors appropriately.
Here’s an example error response from the serviceUpdate mutation:
{
"data": {
"serviceUpdate": {
"service": null,
"errors": [
{
"message": "This service is locked by a service config file.",
"path": [
"locked"
]
}
]
}
}
}
Integrating OpsLevel API into your own App
1. Create an API Token
In the OpsLevel app, navigate to the API tokens page by pressing the API link in the side menu or by navigating to https://app.opslevel.com/api_tokens.
From this page, press the + Create API Token button.
After pressing the + Create API Token button, you will be prompted to add a Token Description. Once you’ve added a description, press the Create API Token button shown below.
After your token has been created, you will be shown a confirmation modal with your new API token.
Important: You will only be shown your API token once upon creation. Store it somewhere safe. If you lose this token, it’s irrecoverable by OpsLevel.
Tokens are to be used in the Authorization header of your request as a Bearer or Token.
Note: <token> will be used in place of your actual token in all examples.
2. Make a request with curl
To test that everything is working correctly, copy and paste one of the following curl commands into your terminal and replace <token> with the token generated in the previous section.
GraphQL query
TOKEN=<token> # ... paste in your API token
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer ${TOKEN}" \
-d '{ "query": "{ account { name } }" }' \
https://api.opslevel.com/graphql
You should receive the following response:
{"data":{"account":{"name":"Your Account Name"}}}
where "Your Account Name" is replaced with your actual account name.
GraphQL mutation
You can also apply a mutation, such as creating a new service, with the following:
TOKEN=<token> # ... paste in your API token
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer ${TOKEN}" \
-d '{ "query": "mutation { serviceCreate(input:{name:\"Brand New Service\"}) { service { id name } errors { message path } } }" }' \
https://api.opslevel.com/graphql
3. Make a query with your favourite client library
Underneath it all, GraphQL APIs are built on top of HTTP, so you can use your existing HTTP libraries and tools. GraphQL is widely supported by a variety of languages and frameworks through client plugins, such as Apollo for Javascript and graphql-client for Ruby.
We also have built a golang client which is being developed in tandem with our CLI, Terraform provider and kubectl sync.
For a great list of GraphQL plugins for both server and client applications, refer to https://github.com/github/graphql-client.
GraphQL Examples
Querying Service Information
Query all services with their team name and manager contact info
{
account {
services {
nodes {
name
aliases
description
owner {
name
manager {
email
}
}
}
}
}
}
Query all services with owner, aliases, tags, tier, and repositories
{
account {
services {
nodes {
name
description
owner {
name
}
aliases
tags {
nodes {
key
value
}
}
tier {
alias
name
}
repositories {
totalCount
nodes {
name
defaultBranch
private
url
}
}
}
}
}
}
Query services with criteria - Ruby on Rails services
{
account {
services(language: "Ruby", framework: "Rails") {
nodes {
name
aliases
description
language
framework
}
}
}
}
Query services with criteria - Tagged with public-facing:true
{
account {
services(tag: {key:"public-facing", value:"true"}) {
nodes {
name
aliases
description
tags {
nodes {
key
value
}
}
}
}
}
}
Query a specific service by its alias
{
account {
service(alias: "shopping_cart") {
name
aliases
description
}
}
}
Query a specific service by ID
{
account {
service(id: "Z2lkOi8vb3BzbGV2ZWwvU2VydmljZS8xMzM") {
name
aliases
description
}
}
}
The OpsLevel API offers more queries which can be found in GraphiQL’s Docs tab.
Pushing Service Information
Registering a new service with OpsLevel
mutation {
serviceCreate(input: {
name: "New Service",
tierAlias:"tier_1",
description:"This is a description for the new service"
language: "Java",
framework: "Spring",
ownerAlias:"a-team"
}) {
service {
name
description
owner {
name
}
tier {
alias
name
}
}
errors {
message
path
}
}
}
Updating a service
Using the ID of the service
mutation {
serviceUpdate(input: { id: "Z2lkOi8vb3BzbGV2ZWwvU2VydmljZS8xMzM", name: "Updated Service Name" }) {
service {
name
}
errors {
message
path
}
}
}
Using the alias of the service
mutation {
serviceUpdate(input: { alias: "shopping_cart", name: "Updated Service Name" }) {
service {
name
}
errors {
message
path
}
}
}
Deleting a service from OpsLevel
Using the alias of the service
mutation {
serviceDelete(input: { alias: "shopping_cart" }) {
deletedServiceId
errors {
message
path
}
}
}
The OpsLevel API offers more mutations which are documented in GraphiQL’s Docs tab.
Managing Tags Information
Querying tags from a given Service
Using the ID of the service
{
account {
service(ID: "Z2lkOi8vb3BzbGV2ZWwvU2VydmljZS8xMzM") {
name
tags {
nodes {
key
value
}
}
}
}
}
Using the alias of the service
{
account {
service(alias: "shopping_cart") {
name
tags {
nodes {
key
value
}
}
}
}
}
Assigning tags to a service
The tagAssign mutation is an ‘upsert’-style mutation: if a tag with the same key already exists it will be updated, otherwise a new tag will be created.
This is useful as way to easily push tags into OpsLevel without having to do a query.
Assigning Tags
mutation {
tagAssign(input: {
alias: "shopping_cart",
tags: [
{ key:"database", value:"mysql-5.8" },
{ key:"queue", value:"sidekiq" },
]
})
{
tags {
id
key
value
}
errors {
message
}
}
}
Deleting Tags
To delete a tag, you must to inform the id of the Tag.
mutation {
tagDelete(input: { id:"Z2lkOi8vb3BzbGV2ZWwvVGFnLzU" }) {
errors {
message
}
}
}
Frequently Asked Questions
What happens if I lose my API token?
For security purposes, API tokens are irrecoverable by OpsLevel. If you lose your API token, you can delete it and create a new one.
Who else uses GraphQL?
GraphQL is gaining popularity rapidly because of the benefits it provides. Companies such as Facebook, Twitter, Shopify, GitHub, GitLab, and many many more use GraphQL today.
What if I have more questions or suggestions?
If you have any questions, suggestions, or just want to chat, reach out to us at info@opslevel.com.