Rapier: Cut Through the Tedium of API Specification
At Apigee, we're big believers in the importance of API metadata for all aspects of the API lifecycle—we were one of the early promoters of Swagger and a founding member of the OpenAPI Initiative. We never stop thinking of ways to make API design and development better, and to that end, we've set up an Apigee Labs organization on GitHub as a place to incubate new ideas.
Today, we want to share with you a new project that we're working on—Rapier—that is a proving ground for some of these ideas. Some are ideas that we may propose for inclusion in future versions of the OpenAPI Specification, and others may become part of Apigee's roadmap, but for now, we just want to get these into a wider discussion and solicit feedback in the spirit of open development.
Rapier is a new API specification language created by Apigee. The goals of Rapier are to allow REST APIs to be specified and learned with one-tenth the effort required with other API specification languages, and to produce specifications that describe higher-quality APIs1. Rapier is published in this public repository under an Apache 2.0 license—it will be managed as an open source project.
The name Rapier is an acronym for “REST APIs from entities and relationships.” With Rapier, you specify an API in YAML by specifying the entities and relationships of the data model that underlies the API, along with query paths traversing the relationships.
The details of the API's HTTP messages are deduced from this specification using the standard patterns described in the HTTP specifications, plus a few conventions that we have added. Rapier thereby eliminates the need to repetitively document individual URLs and their methods, which vary only in the entities they accept and return or the queries they express.
Rapier is for specifying new APIs. You won’t be able to describe an existing API with Rapier unless that API uses the same conventions that Rapier does and is perfectly consistent in applying them.
A data-oriented approach to specifying new APIs
Rapier takes a data-oriented approach to API design, which aligns with the model of the world-wide web. If your mental model of an API is a network of HTTP resources identified and located using URLs, you should be comfortable with Rapier. If you think of a web API as a set of “end-points” with “parameters” (a traditional service-oriented or RPC model), the Rapier approach may not resonate with you. While Rapier APIs conform to the principles of REST, including the provision of hypermedia links, Rapier APIs do not require special clients that adapt to changing server data formats—most clients of Rapier APIs are quite conventional.
Because the Rapier specification language is an experiment and neither widely known nor adopted, we provide a tool that will generate an OpenAPI Specification (or OAS, formerly known as Swagger) document from a Rapier specification. The generated OAS document allows you to learn the precise details of the HTTP messages implied by the Rapier specification, the HTTP specifications, and our additional conventions. Generating OAS documents is also useful for integrating with tools that are based on OAS, or for communicating with people who know OAS but not Rapier. OAS remains important for documenting APIs that follow a service-oriented rather than a data-oriented design pattern, or follow different conventions than the ones Rapier currently understands, or are less consistent than Rapier APIs. Rapier is designed to complement, not replace, OAS.
Try it out
Rapier is very easy to understand and learn. The easiest way is by example. Rapier builds on top of JSON Schema, so if you aren’t familiar with that standard, you should spend a few minutes getting some level of understanding of what it looks like and what it does. Then you should be ready for this tutorial.