Announcing RAML

On behalf of the RAML Workgroup, I am excited to unveil the RESTful API Modeling Language today as an open spec. This project’s been under development for quite some time, while we’ve been battle testing it and utilizing it to improve our own internal APIs. As we began socializing the spec for feedback from several API experts, we were humbled to see mounting interest from folks who got deeply interested in collaborating on the direction of the spec. As a provider, an API is the capability you offer others (inside your company or outside) to derive your value, to add theirs, to create and realize opportunities. As a consumer, an API is what you build on to realize the provider’s value or to generate even more value. So an API is a contract between provider and consumer, around an interface. Both the provider and the consumer have to build around a common definition for that API. The success of the API depends on how well this contract works, as well as how well it’s implemented on both sides. RAML is a language for expressing that interface, that contract, optimized for the users of the contract: the consumers and the providers. In defining RAML, we looked to address some of the practical and pervasive problems across nearly all APIs. It seeks to address the overarching concerns of any API strategy, in as lightweight a way as possible:

• As a provider, what am I committing to deliver (for an extended period of time)?
• As a consumer, what can I rely upon to be available (for an extended period of time)?
• If I’m responsible for a whole initiative, say a mobile one, how can I best ensure it’ll work, on-time and on-budget?
• As a provider, how can I attract devs to my offering, and make them more successful?
• As a consumer, how do I quickly find, learn, and ensure I’m building on a good foundation?

In an ideal world, you could design the API to fit these needs, nail down the design in a spec, then implement the spec. But you don’t necessarily know your needs immediately: you have to iterate a bit, play with it, until you have it right. Same as when you develop a killer UI. So you need a design-first approach to your APIs, and you need it to be easy and agile… how do you do that? Say hello to RAML. RAML emerged to the world today. You can expect new projects and tools to be available very shortly to help further show the benefits of RAML, of a design-first approach, and of a consumer-oriented strategy. In the meantime, I encourage you to have a look at the RAML tutorials to see just how we’re approaching things.