It has been an exciting summer at Apiary. I joined at the beginning in June to lead Apiary’s enterprise project. This week, we’ve crossed 100,000 APIs described in Apiary. And today, we announce the result of a lot of discussion with customers — Apiary for Enterprise. As APIs are becoming mainstream, large teams around the world are solving the same problems: making sure that their APIs adhere to the same, shared design principles. Apiary for Enterprise is designed to solve that problem once and for all.
Again and again, we heard the same story from developers working on larger API projects. The story involves what some call an “API style guide”, but it goes by many names. Some projects refer to it as “contract authoring guidelines”. No matter what the name, it reflects a need to ensure consistency in the APIs being developed by multiple teams.
Throughout the API lifecycle, there are a million decisions that need to be made, some minor some significant. Some of the big ones:
Then there are the seemingly insignificant decisions:
PUTor also support
If you are an API architect or an API product manager, you may have spent a significant amount of time developing an API style guide. Or, more likely, you’ve been thinking about creating one.
The style guide encodes all of the best practices, random coin tosses, and also resolves theological debates about contentious topics like REST and hypermedia. However, the style guide is only as good as your ability to socialize it. Manual reviews of API designs might help to some extent. But as APIs are implemented, deployed, and versioned, how can you be sure whether interfaces that form the contract between your organization and the developer have not changed?
Once organizations finally settle on a set of guidelines, there’s a new challenge: how to ensure that APIs adhere to the guidelines, without imposing an undue burden on developers? The design guide needs to work from the bottom up, or else it risks being resisted, or worse, ignored. Constantly consulting a document just adds another level of ‘bureaucracy’, slowing down the deployment of APIs.
To address this need, Apiary is introducing a programmable layer on top of API Blueprint. This layer can be be used to codify the basic design rules that are established in an organization’s API style guide.
In keeping with the Apiary’s developer-friendly ethos, we have kept Apiary for Enterprise lightweight, elegant, and usable. Our goal is to make all developers lives easier, whether they are implementing or consuming APIs. By providing real-time feedback on API designs, we hope to ensure that developers spend less time refactoring inconsistent APIs, and more time building new ones. We also hope that developers who consume APIs will have an easier time as APIs become more predictable and consistent.
To know more about this plan and its features, you can contact me at firstname.lastname@example.org.