API V3 is Here!
After many months of work by our Platform Engineering Team (and some of our Infrastructure and Support engineers too!) we’re super excited to finally announce the release of the Travis CI API Version 3!
We’ve been working on V3 for quite some time, originally conceiving of it in Q4 of 2014. Our primary goals were to improve and modernize our API, speed up the request/response cycle, reduce the number of API calls our UI makes, and clean up the codebase by decoupling its dependency on the monolithic
travis-core gem (which we spent most of last year removing from our other Platform apps).
We also wanted something to encourage outside developers to contribute to the API and build 3rd party applications to consume it. We’ve already seen a bunch of great tools to interact with Travis CI built by developers in the broader Travis community. We wanted to improve our support for these developers and facilitate their on-going work.
The end result is an API that’s functional and well structured, that uses standardized formats and RESTful endpoints, with responses that are discoverable and self-documenting, and which includes all the hypermedia features expected from a modern API. We’ve also created API Developer Documentation that closely integrates with V3, updating automatically when new endpoints are added, and includes a useful tool for exploring endpoints (see below).
New features of V3 include:
Optional nested resources which can be included to get additional data in a single request;
Built in pagination and query scoping, allowing for speedier response times when querying large tables;
The ability to follow hypermedia queries programmatically;
Auto-discovery of available actions, response types, and permissions, allowing the API to be extended without client libraries needing frequent updates;
Consistent and informative error messages.
What can you do with it?
Our API can be used to automate many of your Travis CI build processes. Examples include:
- get build information
- get organization information
- get nested resources
- trigger a build (a feature that’s been available for some time)
- restart builds or jobs
- cancel builds or jobs
- trigger debug builds
- deal with pagination
- edit environment variables
- validate the
…and much more!
The API Explorer in our API Developer Documentation allows you to perform API calls to api.travis-ci.org. You can copy and paste URLs to share examples with your colleagues, and you can copy and paste the calls we make directly to your terminal for use with curl. Please Note: You will need to be logged in to Travis CI in order to access the API Developer Documentation.
The API Explorer also provides information about your unique Travis CI API token. The token appears redacted until you hover over it, so you can take screen shots while keeping your token hidden.
API V2 Deprecation
We’re not yet ready to deprecate V2 of our API. We use V2 with our web frontend application and have spent the last 6 months switching gradually from V2 to V3. We’ll complete this transition in the coming months, but plan to continue supporting V2 until the end of 2017. We’ll naturally give developers ample notice before switching V2 off, and provide detailed instructions for making the transition to V3. However, we do encourage you to start making the transition now.
V3 of our API is already included in the recent 2.1 release of Travis Enterprise.
Our V3 API can be found at the following links:
If you would like to leave us feedback on your experience using API V3 or our new API Developer Documentation, please add a comment on this GitHub issue.
If you’re having a problem with API V3, please open a support ticket by emailing email@example.com