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-clientGenerating 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?
Readable Requests and Responses with RAML
By Nathan Dunn
