What is the API - GraphQL?

The API is an endpoint to programmatically get data from the eSuite environment with an API call. Requesting data can be done with the GraphQL language. (https://graphql.org)

How do I know what data I can get or submit via the API?

The GraphQL language has built in documentation. When we provide you with the correct URL to connect to the API, your tool of choice should have documentation on the available endpoints and parameters you'll have to provide and the results you can expect. 

How do I authenticate to the API?

The API is not publicly available. This means that you’ll have to authenticate yourself while you are requesting data from the API. For this authentication, we use a token which can be generated for a specific user in the eSuite application.

• Getting a token
  • Go to the admin of the eSuite.
  • Go to the "users"-page and select a user for which you want to generate a token.

• • Go to the section "Access Tokens" and click on generate token

• • The eSuite will generate a new token. Which can only be seen once and is valid for one year. After a year, when a new token is generated for that user, or when the token is specifically deleted. The previous token will not be valid anymore and you’ll have to create a new one.

• Using the token
  • You can contact our support to receive the correct URL.
  • Now that you have the token, you’ll have to add it to the requests you are going to make. The token needs to be added as the password of the basic-authentication header. We’ll add some examples with different tools:
    • Postman: In this tool you have to go to the tab "Authorization", then select "Basic Auth", and paste the token in the Password field.

• • API Playground: Here you’ll have to go to the "Connection Settings". This can be found in the upper right corner. Then go to the "Authorization" tab. Select "Basic" and paste the token in the Password field.            

• • Manually: If you are not using a tool, you’ll have to follow the official documentation of Basic-Authentication. (https://en.wikipedia.org/wiki/Basic_access_authentication) 
    • Base64 encode the token with a colon in front of the token. (example: “:0bb3a679-8c1e-4836-a8a3-090708373ae1”)
    • Add the Authorization header to your request as follows: “Authorization: Basic #here comes encoded string#”
• Finding the correct calls and properties you can request.
  • API Playground: Go to the tab "Schema Reference". Here you'll find all the endpoints and properties that you can request

• Getting the data
  • For the syntax used for a GraphQL-request, we forward you to the official documentation of GraphQL (https://graphql.org). We will however add some small examples and tips to start requesting data or you can go to a specific article:
    • A simple request that can be made is:

query {
  currentApplicationUser {
    id
    firstName
    lastName
  }
}

• • A more advanced request with some parameters is:

query {
  basePerson(id: 295) {
    id
    firstName
    lastName
  }
}

• • A big part of GraphQL is that you can nest data in your request. In the following example we also request some subdata of the person:

query {
  basePerson(id: 295) {
    id
    firstName
    lastName
    address {
      street
      number
      country {
        name
      }
    }
  }
}

• • If you want to add/push data into the eSuite instead, the call becomes a little bit more advanced with the use of mutation instead of query (see specific article). Here we need to create a $user variables. Which then we can add data in the separate variables section:

mutation saveUser($user: UserInput!) {
  saveUser(user: $user) {
    id
    firstName
    lastName
  }
}

Variables:

{
  "user": {
    "id": 295,
    "firstName": "NewName"
  }
}