23 Apr 2020 · Semaphore News

    Introducing the new Semaphore API

    5 min read

    We’re happy to announce the release of Semaphore API v2.

    The new API brings greater clarity, improves usability, and fixes the key issues in API v1. This new version is a complete rewrite of our API, both in terms of functionality, and the underlying design principles.

    Why is Semaphore releasing a new API version?

    Semaphore announced a public API in its first year of release. We’ve come a long way since then, both in terms of the number of active users and the number of features offered on Semaphore.

    Driven by popular demand to expand our API, and the necessity to combat the tehnical limitations of the old implementation, at the start of this summer we decided to establish new API design principles and bootstrap a fresh and improved Semaphore API.

    We set up a new subdomain dedicated for API access to Semaphore api.semaphoreci.com, and started exposing core resources.

    The API v2 strives to solve key problems and lift the limitations of the old API v1.

    Key differences between API v1 and API v2

    The old API v1 served us well over the years, but several core issues limited our progress and worsened the usability of the API. Here are some of the API v1 issues addressed in our new API:

    API stability is not defined: Resources in the API v1 have no clear life-cycle. As soon as a new endpoint is published, it becomes production-ready, and subject to strong modification rules. This prevented us from publishing early and often, communicating with our customers, and implementing feedback we received from them.

    Lack of API schema: The development of API v1 was not following strict guidelines, and most of the endpoints were added ad-hoc. This resulted in a public interface that was inconsistent, making it difficult for our customers to learn it, and for our developers to add new features without worrying about the possibility of worsening the usability of the API.

    Pagination was not built in: Pagination in the API v1 was not a default feature for all endpoints that return collections. Some endpoints implemented them, but some of them did not.

    With several years of experience under our belts, the API v2 was designed to combat these issues and open the doors for automated client and documentation generation. These are the most important features in API v2:

    Every resource has a stability level: When a new resource is published, it is released with the prototype stability. This allows us to communicate with our customers and make rapid adjustments in the interface. Following the prototype phase, we change the stability to development. A development resource is a work-in-progress, but major changes should be infrequent. In time, development resources should advance to production stability, where major changes should not occur.

    Flat resource hierarchy: Contrary to API v1, API v2 prohibits deep resource nesting. All resources are flat (e.g. https://api.semaphoreci.com/v2/projects), and relationships between resources are nested one level deep (e.g. https://api.semaphoreci.com/v2/orgs/renderedtext/projects). Deeper nesting is prohibited. This limitation improves the usability of the API, and makes it easier to automatically generate clients and documentation.

    Multiple auth methods: API v2 allows authentication either via the authorization header, or query parameters, and enforces HTTPS for all requests.

    Pagination is built in: Every API v2 resource has pagination by default. All responses are paginated to 30 resources, and use HTTP headers for navigation.

    API v2 is open source: With API v2 we decided to embrace an open and transparent development model as much as possible. The API specification, Ruby clients, documentation and tooling are all developed and released as open source on GitHub.

    Testing out the new API

    The best place to start exploring our new API is the root path https://api.semaphoreci.com/v2 and the API v2 overview documentation page.

    For example, to list your organizations via API v2, you can use the following curl snippet:

    $ export AUTH_TOKEN=
    $ curl "Authorization: Token $AUTH_TOKEN" https://api.semaphoreci.com/v2/orgs

    You can find your API auth_token at the bottom of your user settings page.

    End of life for API v1

    The old API v1 is considered deprecated. We will continue to provide full support for API v1, but no new feature will be released as part of the old API.

    The old API v1 will be available for one more year, and will be turned off at September 2018.

    The future

    In the upcoming period, we plan to release several new features closely tied to the release of the new API.

    Team management, adding projects over API, a Ruby client for the API, and a command line interface for Semaphore are some of the exciting new features we are working on.

    Is there a feature you would like to see as part of our new API? Let us know in the comments below. We’re looking forward to reading your feedback.

    If you’re new to Semaphore, learn more about our hosted continuous integration and delivery service, or click here to sign up.

    Happy building!

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    Writen by:
    Chief Architect at Semaphore. A decade of experience in dev productivity, helping close to 50,000 organizations with operational excellence.