API

Screwdriver APIs and the data models around them are documented via Swagger. This prevents out-of-date documentation, enables clients to be auto-generated, and most importantly exposes a human-readable interface.

Version 4 is the current API, all links should be prefixed with /v4.

Our API documentation can be found at api.screwdriver.cd/v4/documentation. To see yours, go to /v4/documentation.

Using the API

With Swagger

Swagger documentation includes examples and editable parameters to play around with. Visit the /v4/documentation page and use the interactive Try it out! buttons to make calls to our API.

Swagger page: Swagger page

Response: Swagger response

With a REST Client

Use a REST client like Postman to make requests against the API. You will need an authorization token. To get an authorization token, login using /v4/auth/login and copy the token value when redirected to /v4/auth/token. See the Authorization and Authentication section for more information.

Requests can be made to the API with headers like below:

Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN_HERE>

Example request: Postman response

For more information and examples, check out our [API documentation].

Authorization and Authentication

For Authentication we're using JSON Web Tokens. They need to be passed via an Authorization header. To generate a JWT, visit the /v4/auth/login endpoint which will redirect you to the /v4/auth/token endpoint.

Authorization on the other hand is handled by OAuth. This occurs when you visit the /v4/auth/login endpoint. Screwdriver uses SCM user tokens and identity to:

For more information, see the GitHub OAuth documentation.

Design

Our API was designed with three principles in mind:

  1. All interactions of user's data should be done through the API, so that there is a consistent interface across the tools (CLI, Web UI, etc.).
  2. Resources should be REST-ful and operations should be atomic so that intent is clear and human readable.
  3. API should be versioned and self-documented, so that client code generation is possible.

Make Your Own

If you'd like to make your own Swagger documentation, check out our JSON for reference at https://api.screwdriver.cd/v4/swagger.json. To see your Swagger.json, visit /v4/swagger.json.