WHAT IS RAML?
RAML stands for RESTful API Modeling Language. It's a way of describing practically-RESTful APIs in a way that's highly readable by both humans and computers. We say "practically RESTful" because, today in the real world, very few APIs today actually obey all constraints of REST. RAML isn't strict: for now, it focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, RESTful constraints.
RAML is a non-proprietary, vendor-neutral open spec. The aim is to help our current API ecosystem and solve immediate problems, and then gently encourage ever-better API patterns.
WHY SHOULD I USE RAML FOR MY API?
You'll get a well-defined contract in a human-readable format to actually exist as your source code.
Your API's structure is manifest and easily understood by everyone: developers, partners, and other API-consumers.
The Application Programming eXperience, or APX, vastly improves with the knowledge that there is a formal, versioned, crystal-clear contract that reflects the structure of the API and is independent of implementation.
Well-designed and manifestly-structured APIs, with a lot of internal consistency based on explicit patterns, lead to easier and more robust client coding and server implementations.
RAML DESCRIBES AN API IN A WAY THAT IS
Clear: The structure of the API should be manifest. Patterns are brought to the forefront; its data and interaction models are front and center.
Correct: An API spec is a contract: whatever is captured must correctly describe the behavior of the API.
Precise: Can a client be generated from the spec that's as faithful to the API as it is reasonable? Do the implementers know what they're required to deliver?
Consistent: RAML has strong support for capturing patterns. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.
Readable & writable: Optimizes both creating and reading specs by impatient, smart humans.
Natural & intuitive: It is as close as possible to the mental model one has for the API, like what you'd type out in an email to a colleague or friend you were helping design or consume the API.
GETTING STARTED WITH RAML
See how easy it is to get started with the RAML 100 tutorial. We will be adding additional documentation on an ongoing basis.