Readable Requests and Responses with RAML

@nathanjdunn

What even is RAML, anyway?

  • RESTful API Modelling Language

  • YAML-based syntax

  • First proposed in 2013

  • Developed and is supported by RAML workgroup

Why use RAML?

  • Design - RAML lets you describe your API in a human readable format.

  • Build - Use generators to create the backend for your application (PHP, Node.js, Java libraries available).

  • Test - After defining your spec, you’re able to run automatically generated tests in your CI environments.

  • Document - Generate API documentation for your users from your RAML config.

#%RAML 1.0
title: Posts API
version: v1
baseUri: http://api.samplehost.com

/posts:
  get:
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "title": "Hello World"
                "body": "Lorem ipsum dolor sit amet.
              }

Basic Example

npm install raml2html -g

raml2html api.raml > api.html

Generating HTML Docs

npm install raml-php-generator -g

raml-php-generator api.raml -o php-client

Generating a PHP Client

#%RAML 1.0
title: Posts API
version: v1
baseUri: http://api.samplehost.com

traits:
 - orderable:
     queryParameters:
       orderBy:
         description: |
           Order by field: <<fieldsList>>
         type: string
         required: false
       order:
         description: Order
         enum: [desc, asc]
         default: desc
         required: false

/posts:
  get:
    is: [
        orderable: {fieldsList: "title"}
    ]
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "title": "Hello World",
                "body": "Lorem ipsum dolor sit amet."
              }

Traits

Considerations

  • Retrofitting existing APIs

  • Alternatives (e.g. API Blueprint, Swagger)

Useful Links

Any questions?

Made with Slides.com