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:
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:
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:
If you have feedback, please provide it by opening a GitHub issue.
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:
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.