Introduction
Centralizing and collaborating on ops jobs is powerful, but you unleash the full potential of drush.io when you embed it into your day-to-day working environments and processes.
Use the drush.io API to run jobs in the right places at the right time:
- Integrate with your chatops platform and deploy from your team’s channel,
- Build a friendly UI for site editors to trigger platform operations,
- Augment your ticket tracking, VCS, IDE, or code review tools with platform integrations,
- Trigger terminus commands from quicksilver scripts
All via a simple, RESTful JSON API! Start by diving into authentication.
Authentication
All API requests on drush.io are authenticated using JSON web tokens (JWT) scoped to your account. In order to run any commands, you must generate a token using the drush.io UI.
-
First, log in to drush.io. By default, you’ll be taken to the
Projects
tab on your account dashboard. -
Navigate to the
Integrations
tab and click theGenerate Token
button. -
A dialogue will appear where you must provide a name/description for your token. We recommend you provide some detail about the context in which you’ll use the token, e.g.
chatbot integration
. -
Click the
Generate
button. Another dialogue will appear, showing your JWT. This is the only time you’ll ever see this token, so note it and keep it safe.
Note that this token grants the same access to the platform as your account and can be used to run jobs for any project you may be a member of. This token is valid until you revoke it.
Authenticating Requests
The JWT should be provided in the Authorization
header of every request you make to the platform. Use the Bearer
authorization type, like this:
POST /v1/projects/my-project/jobs/my-job/runs HTTP/1.1
Host: api.drush.io
Accept: application/json
Content-Type: application/json
Authorization: Bearer {api.token}
Where {api.token} is the JWT token you generated, without any quotes or brackets.
Note that all requests to the drush.io API must be made over https. To keep your account safe, be sure to revoke any API tokens that you are no longer using.
Now that you know how to authenticate requests, learn how to run a job!
Running Jobs
Triggering a job run is as simple as a single HTTP POST request! All you need to know are identifiers for the project and job and you’re ready to go.
All API requests should be made against the base URL https://api.drush.io/v1
and should accept application/json
responses.
Jobs, which are scoped to projects, live at a path like the following:
/projects/{project-ish}/jobs/{job-ish}
- {project-ish} can either be the project machine name (which you supplied when creating the project and is visible on the
Projects
tab on your account dashboard) or the project ID (part of the URL of your project dashboard). - {job-ish} likewise can either be the job machine name (which is generated when you save the job) or the job ID.
We recommend you use machine names where possible to make your API calls easier to understand at a glance. Keep in mind that project and job machine names are editable, while IDs can’t be changed.
Simple job triggers
Think of triggering a job as the act of creating a job run. In HTTP terms, this would be a POST
request to the /runs
sub-resource, like this:
curl --request POST \
--url https://api.drush.io/v1/projects/{project-ish}/jobs/{job-ish}/runs \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {api.token}' \
--header 'Content-type: application/json'
The API will respond with a JSON payload representing a single job run, containing at least the following:
{
"id": "3abed1d7-68ec-4151-ae87-edcc918315b4",
"status": "queued",
"duration": 0,
"created": 1498714037,
"changed": 1498714037
}
Passing variables as context
As highlighted in the variables section of the Jobs and the Runtime documentation, variables can be used to make a single job useful in multiple scenarios.
To run a job using different variable values, pass in the variable values in the POST request body as JSON, like this:
curl --request POST \
--url https://api.drush.io/v1/projects/{project-ish}/jobs/{job-ish}/runs \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {api.token}' \
--header 'Content-type: application/json' \
--data '{"env": {"VAR_NAME": "var-value"}}'
The structure of the request body is a simple object whose keys are variable names and values are variable values, which is itself nested under an env
key. Or, in formatted JSON, something like this:
{
"env": {
"VAR1": "value1",
"VAR2": "value two"
}
}
Creating a job run takes almost no time because it simply queues the job to be run. The actual execution of the job happens asynchronously. If you need to react based on job run status, you must poll for details on the run.
Job Status
Reading a job run is a simple GET
request. Recall that the response payload on job run creation resembles the following:
{
"id": "3abed1d7-68ec-4151-ae87-edcc918315b4",
"status": "queued",
"duration": 0,
"created": 1498714037,
"changed": 1498714037
}
A job run can be read and re-read at a path like the following:
/projects/{project-ish}/jobs/{job-ish}/runs/{run-id}
Where {run-id} is the id
property returned in the response during job run creation. A CURL command to read a job run would look like the following:
curl --request GET \
--url https://api.drush.io/v1/projects/{project-ish}/jobs/{job-ish}/runs/3abed1d7-68ec-4151-ae87-edcc918315b4 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {api.token}' \
--header 'Content-type: application/json'
As a job’s status moves from queued
to running
to complete
or error
, its properties will reflect those changes: duration
, the number of seconds a job takes to execute; changed
, the last time the status was updated.
Once a job has completed execution, if the job generated log output, it will be returned on the log
property, like this:
{
"id": "3abed1d7-68ec-4151-ae87-edcc918315b4",
"status": "complete",
"duration": "26",
"created": "1498714037",
"changed": "1498714068",
"log": " [notice] Command: my-corp.test -- drush cc all [Exit: 0]\n\n"
}
Use strategies like exponential back-off to efficiently poll on the job run endpoint until it is in either a complete
or error
state.
Don’t want to code out the whole solution yourself? Build on top of existing drush.io API clients.
Libraries
Want to get off the ground quickly? Use one of the community supported API clients: