More Flexibility Than Ever - Codeship API v2

“As of January 10th, 2017, we released a Go client for Codeship’s API. To learn more, read the documentation article.

It’s finally here! After months of planning, building, and testing, we’re super excited to announce that the public beta of Codeship API v2 is available as of today!

We’re always aiming to make Codeship super flexible and easy to use, but we also know that sometimes we’re just not flexible enough. Maybe you want to pull some build stats to show in a custom dashboard, or perhaps you’re looking to fully automate a more complex workflow. With the new API, you can do all that and probably a lot of other things we haven’t even thought of yet.

Requested Scenarios

For this initial release, we’ve focused on a couple of the most requested scenarios:

• Custom dashboards - Combine Codeship data with data from other systems in your own dashboard.

• Project automation - Fully automate the setup and configuration of projects, by using templates and/or auto-create projects when new repos are added.

• Build triggering - Start/stop/restart builds based on your own custom logic.

• Chaining projects - Automatically trigger builds on downstream projects.

By focusing on these as starters, we were able to get the API in your hands faster and at the same time provide a lot of value right away.

In terms of specific endpoints, these goals mean that we now have create, read, and update for projects as well as create, read, and trigger builds. Each of the endpoints are described in more detail in the API documentation.

New Authentication and Authorization Models

We’ve also revamped the authentication logic compared to v1 of the API. Instead of an API key, we now use short-lived tokens. Although this will mean that you need to authenticate with the API more often, we believe it’s a more secure approach.

Compared to API v1, the authorization model itself has also changed drastically. Instead of a single API key that gives access to everything, v2 now relies on the teams and roles, inside the Codeship account, of the authenticating user. This means that you can now create a contributor user for your dashboard or a project manager user who can only access the few projects where you want to programmatically trigger new builds.

Read more about authentication in the API documentation.

Why a Beta?

We’re sure there are workflows that we haven’t come across yet, or there could be small things we’ve overlooked. So, to ensure we have a fully working API before calling it done, we want to have more people use it and push the boundaries.

The beta tag is in no way a reflection of a lower quality -- you can start to use the API in production right away. We’re simply looking at this beta as a way to ensure we've covered all the bases.

Some other things to be aware of as you explore the beta include our approach to rate-limiting and log output.

Rate-limiting

To avoid completely overloading the API, we’ve added rate-limiting per IP address. We don’t want one user to be able to negatively impact everyone else, so we’ve set the limit at 60 requests per minute. If you go over that limit, we simply won’t provide an answer until the counter rolls over, at which point you have another 60 requests.

Log output

In terms of functional limits, one of the things we wanted to make available via the API but weren’t able to just yet are the output logs from your builds. Unfortunately, we need to make some changes to how we manage and store the logs for that to be efficient and scalable enough. We’re hoping to be able to add log output later in the year.

Next Steps

Over the next couple of months, we expect to solidify the API, iron out any last kinks, and likely add a couple of additional endpoints based on the feedback we receive during the beta.

We’re naturally also super excited to see what you are going to build with the API, and we'll be happy to help you get started and answer any questions you have about the API. The best option will be to join our community Slack group, where others might also be able to help you out, but you’re welcome to submit a support ticket instead.

The API is available today for everyone, and the documentation can be found here.