about-raml.html

---
layout: page
title: About RAML
permalink: /about-raml
---

<h2>WHAT IS RAML?</h2><p>RAML stands for <strong>RESTful API Modeling Language</strong>. 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.</p><p>
    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.</p><h2>WHY SHOULD I USE RAML FOR MY
    API?</h2><p>You'll get a well-defined contract in a human-readable format to actually exist as your source code.</p>
<p>Your API's structure is manifest and easily understood by everyone: developers, partners, and other
    API-consumers.</p><p>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.</p><p>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.</p><h2>RAML DESCRIBES AN
    API IN A WAY THAT IS</h2><p><strong>Clear:</strong> The structure of the API should be manifest. Patterns are
    brought to the forefront; its data and interaction models are front and center.</p><p><strong>Correct:</strong> An
    API spec is a contract: whatever is captured must correctly describe the behavior of the API.</p><p>
    <strong>Precise:</strong> 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?</p><p><strong>Consistent:</strong> RAML has strong
    support for capturing patterns. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based
    emergence of best practices.</p><p><strong>Readable &amp; writable:</strong> Optimizes both creating and reading
    specs by impatient, smart humans.</p><p><strong>Natural &amp; intuitive:</strong> 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.</p><h2>GETTING STARTED WITH RAML</h2><p>See how easy it is to get started with the <a
        href="/developers/raml-100-tutorial"><strong>RAML 100 tutorial</strong></a>. We will be adding additional documentation on an ongoing
    basis.</p>