.png)
In June 2017, the Symphony LLC platform engineering team published the OpenAPI specifications for the Symphony REST APIs as an open source project hosted by the Symphony Software Foundation. We think this represents a substantial improvement in how the platform’s APIs are documented, delivered, and consumed by users of these APIs.
To help our community understand why we’ve made this change, I want to share some insight into our API strategy. When Symphony first chose to expose the platform’s capabilities to external developers, we made a conscious decision to define the contract using REST APIs between the product that we develop and third-party code that others develop.
Among other things, this meant that:
- The REST APIs needed to be clearly and unambiguously documented, ideally in machine readable form.
- The specifications needed to be available to as many external developers as possible, since we can’t predict how, when or by whom the platform’s capabilities might be consumed by third-party code.
- No client-side language bindings would be provided, since we knew that our customers and partners use a wide variety of technologies and we didn’t want to be put in a position of having to prioritize the development of one technology against another.
While Swagger was an obvious technology choice for us to meet the first objective, we initially published the specs via our documentation site. This unnecessarily constrained our ability to reach community members (per objective #2), and in doing so undermined the value of the specifications and the community’s ability to address objective #3.
In June of 2017, we were able to address these limitations by publishing the API specifications as open source, and in doing so we’ve seen rapid growth in the number of client language bindings (and via those bindings, bots and integrations) that leverage the capabilities of the Symphony platform. The proof is in the numbers—between 2016 and today we have 2.5 times the number of language bindings, and 60% of those leverage the published YAML files.
So the value of this model is obvious, but what about ongoing management of the project?
We have two somewhat competing requirements for the project; to provide third-party developers with both:
- The API definitions for the GA, shipped version of Symphony.
- The API definitions that will appear in the next version of Symphony, so that developers can test their code and ensure that it continues functioning correctly in this version.
We’ve been using a simple branching strategy to support this requirement—the specifications for each version of Symphony are stored in a dedicated version branch in the repository. The master branch always has the version currently in the production environment. When the API for the next branch is stabilized, a new version branch is created. We plan to have that branch available a few weeks prior to the release being deployed to test environments. When the release goes to production, the version branch is merged to master.
This is where we’d like to hear from you:
- Does this model make sense to you?
- Is it easy to consume?
- If not, what refinements would you propose?
If you have feedback, please provide it by opening a GitHub issue.
Contributing Code
Because the implementations of the APIs described by these specifications are generated from the Java source code and that code isn’t open source yet, we don’t expect there to be functional contributions from the community to this project. If you find unclear or inaccurate descriptions in the YAML files, please open a GitHub issue.
Some of the language bindings haven’t been updated to use these published specifications yet, and the project owners would gladly welcome assistance in enhancing their projects to do so. Of particular note here are:
- RestApiClient: the .NET language binding
- symphony-node-binding: the JavaScript / node.js language binding
Contributing to the Community
Finally, if you’re interested in discussing the broader topics of APIs and language bindings, the Foundation’s API Working Group is dedicated to these topics and meets bi-weekly. Note that while the community is welcome to follow along with the activity of the Foundation’s working groups, active participation in working groups requires Foundation membership.
Watch the Github repository to get notified with updates.
