GraphQL API
The Base API for Midpoint.
To access the Midpoint GraphQL API, you must first get an API key by going to https://console.midpointapi.com, signing in, and pressing the Generate API Key button.
Now you can use your own GraphQL tool or use https://studio.apollographql.com/sandbox/explorer
You must do two things to connect to the Midpoint back-end.
Set the back-end to https://query.midpointapi.com/graphql . In the online Apollo version, this is done by clicking next to where it says “Sandbox” in the upper-left corner and entering the string there.
Set the
Authorization
header to the word "Bearer" followed by a blank space and then your API key. In the online Apollo version, this is done by clicking the gear icon in the “Sandbox” area and using the popup to set the header, so it looks like this:
GraphQL Mutation: createMidpoint
The createMidpoint
query is a mutation that allows the creation of a new Midpoint
object. This query takes an input object of type NewMidpoint
, which contains a required name
field.
Schema
Arguments
input
: An object of typeNewMidpoint
that contains a requiredname
field. This field specifies the name of the newMidpoint
object that is being created.
Return Type
The createMidpoint
query returns a Midpoint
object. The Midpoint type is extremely complex but the object that is created is mostly blank, everything but the ID and name being empty or null.
Example Usage
To create a new Midpoint
object with a name of "New Midpoint", you would use the following query:
This query would return the following result:
This indicates that the new Midpoint
object has been successfully created with the specified name.
GraphQL Mutation: updateMidpointStatus
The updateMidpointStatus
query is a mutation that allows the update of the status
field of a Midpoint
object identified by the id
field. It is used to publish, un-publish, and delete Midpoints. This query takes two arguments: an integer id
representing the ID of the Midpoint
object to update, and an enum status
of type midpointStatus
, representing the new status to set for the Midpoint
object.
If the status
is set to publish
, the Midpoint will automatically be validated (checked for errors that would keep it from working properly); if the validation fails, the Midpoint will not be published.
Schema
Arguments
id
: An integer representing the ID of theMidpoint
object to update.status
: An enum of typemidpointStatus
representing the new status to set for theMidpoint
object.
Return Type
The updateMidpointStatus
query returns a Midpoint
object.
Example Usage
To update the status of a Midpoint
object with ID 123 to "live", you would use the following query:
This query would return the following result:
This indicates that the status of the Midpoint
object with ID 123 has been successfully updated to "live". Note that the Midpoint
object also contains the id
and name
fields to confirm that the correct object was updated. Of course, you can, if you need to, retrieve any other fields you want from the Midpoint.
GraphQL Mutation: createSecret
The createSecret
query is a mutation that allows the creation of a new Secret
object. This query takes an input object of type SecretInput
, which contains three required fields: midpointId
, name
, and value
.
Secrets are stored securely encrypted on our database. They are typically used to hold information that is needed for the operation of a Midpoint but should be kept confidential, such as API keys and passwords.
Schema
Arguments
input
: An object of typeSecretInput
that contains three required fields:midpointId
: An integer representing the ID of theMidpoint
object to associate with the newSecret
object.name
: A string representing the name of the newSecret
object.value
: A string representing the value of the newSecret
object.
Return Type
The createSecret
query returns an integer representing the ID of the newly created Secret
object.
Example Usage
To create a new Secret
object associated with a Midpoint
object with ID 123, with name "New Secret" and value "secret value", you would use the following query:
This query would return the ID of the newly created Secret
object.
GraphQL Mutation: deleteSecret
The deleteSecret
query is a mutation that allows the deletion of a Secret
object. This query takes an input object of type DeleteSecretInput
, which contains two required fields: midpointId
and name
.
Schema
Arguments
input
: An object of typeDeleteSecretInput
that contains two required fields:midpointId
: An integer representing the ID of theMidpoint
object associated with theSecret
object to delete.name
: A string representing the name of theSecret
object to delete.
Return Type
The deleteSecret
query returns an integer representing the id of Secret
object deleted.
Example Usage
To delete a Secret
object associated with a Midpoint
object with ID 123, with name "New Secret", you would use the following query:
GraphQL Mutation: updateMidpoint
The updateMidpoint
query is a mutation that allows the updating of an existing Midpoint
object. This query takes an input object of type UpdatedMidpoint
, which contains four fields: id
, name
, source
, and tasks
. The id
field is required, while name
, source
, and tasks
are all optional. However, if any of these fields are specified, only one field of each TaskInput
and each SourceInput
can be non-null.
Schema
Arguments
input
: An object of typeUpdatedMidpoint
that contains four fields:id
: An integer representing the ID of theMidpoint
object to update. This field is required.name
: A string representing the new name for theMidpoint
object. This field is optional.source
: An object of typeSourceInput
representing the newSource
object for theMidpoint
object. This field is optional; if it is not specified, the value in the Midpoint will remain unchanged.tasks
: An array of objects of typeTaskInput
representing the newTask
objects for theMidpoint
object. This field is optional; if it is not specified, the value in the Midpoint will remain unchanged.
Only one value may be specified for any SourceDefinitionInput
or TaskDefinitionInput
object.
Return Type
The updateMidpoint
query returns a Midpoint
object representing the updated Midpoint
object.
Example Usage
To update a Midpoint
object with ID 123, with a new name “Updated Midpoint”, a new Source
object, and a new Task
object, you would use the following query:
GraphQL Query: midpoint
The midpoint
query is used to retrieve a Midpoint object based on its unique ID. The query accepts a single required argument id
of type Int
which represents the ID of the midpoint to retrieve.
You are only allowed to retrieve Midpoints that you own.
Schema
Arguments
id
: An integer representing the unique ID of the midpoint object to retrieve.
Return Type
The midpoint
query returns a single Midpoint
object.
Example Usage
To retrieve a Midpoint
object with an ID of 123
, you could use the following query:
GraphQL Query: myInfo
The myInfo
query is used to retrieve information about the authenticated user. This query does not require any arguments.
Schema
Return Type
The myInfo
query returns a single User
object that contains information about the authenticated user.
Fields
The User
object contains the following fields:
id
: An integer representing the unique ID of the authenticated user.name
: A string representing the name of the authenticated user.email
: A string representing the email address of the authenticated user.token
: A string representing the authentication token for the authenticated user. This token can be used as your API key.midpoints
: An array ofMidpoint
objects representing the midpoints associated with the authenticated user.
Example Usage
To retrieve information about the authenticated user, you would use the following query:
GraphQL Query: validateMidpoint
The validateMidpoint
query is used to validate a Midpoint object. The query accepts a single required argument id
of type Int
which represents the ID of the midpoint to validate.
The validation process checks for many errors that might make a Midpoint non-functional, such as:
an empty task list
a cycle in the nexts-path
a missing task int the nexts path
A Midpoint will automatically be validated when you attempt to publish it, but this query can be used to validate the Midpoint without publishing.
Schema
Arguments
id
: An integer representing the unique ID of the Midpoint object to validate.
Return Type
The validateMidpoint
query returns a ValidationResults
object that contains information about the validation results.
Fields
The ValidationResults
object contains the following fields:
success
: A boolean representing whether or not the validation was successful.errors
: An array of strings representing any validation errors that occurred.
If success
is true, the errors
array will be empty; if it is false, there will be at least one entry in the errors
array.
Example Usage
To validate a Midpoint
object with an ID of 123
, you would use the following query:
Last updated