Eddú Meléndez

RAML: Designing an API

As a developers, every day we are working coding many APIs. But, what about design? Sometimes due to the project schedule, too much requirements and even the lack of knowledge about what is REST; developers forget about the design of API.
Months ago I was surfing on the internet, don’t remember where but I read:

RESTis more than work with xml or json.

And that’s true. So, I researched more about REST and learned lot of things.

What RAML is?

RESTful API Modeling Language allow us to design, describe, define the API. It’s human readable and it is visible to everyone.

That’s pretty cool, we can design the API and document as well.

Security

RAML supports authentication:

  • Basic authentication
  • Digest authentication
  • Oauth 1.0
  • Oauth 2.0

Book Store API

In the example below, I have designed a Books Store API working my favourite book list. The API allow me to Create, Read, Update and Delete books. A simple CRUD operation which is represents by HTTP methods.

OPERATION HTTP METHODS
CREATE POST
READ GET
UPDATE PUT
DELETE DELETE 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

#%RAML 0.8
---
title: Book Store API
version: 1.0
baseUri: http://localhost:8081/api
/books:
  displayName: Books Catalog
  get:
    responses:
      200:
        body:
          application/json:
            example: |
                {
                  "bookId": 1,
                  "title": "Angel & Demons",
                  "isbn": "0-671-02735-2",
                  "authors": [
                    "Dan Brown"
                  ]
                },
                {
                  "bookId": 2,
                  "title": "The Da Vinci Code",
                  "isbn": "0-385-50420-9",
                  "authors": [
                    "Dan Brown"
                  ]
                },
                {
                  "bookId": 3,
                  "title": "The Lost Symbol",
                  "isbn": "978-0-385-50422-5",
                  "authors": [
                    "Dan Brown"
                  ]
                },
                {
                  "bookId": 4,
                  "title": "Inferno",
                  "isbn": "978-0-385-53785-8",
                  "authors": [
                    "Dan Brown"
                  ]
                }
  post:
    body:
      application/json:
        example: |  
            {
             "title": "Deception Point",
             "isbn": "0-671-02738-7",
             "authors": [
              "Dan Brown"
             ]
            }
    responses:
      201:
        description: Book has been successfully created.
      409:
        description: Book already exists.
  /{bookId}:
    displayName: Book
    uriParameters:
      bookId:
        description: |
          Book Identifier
        required: true
    get:
      description: Retrieve book-related information.
      responses:
        200:
          body:
            application/json:
              example:  |
                {
                  "bookId": 1,
                  "title": "Angel & Demons",
                  "isbn": "0-671-02735-2",
                  "authors": [
                    "Dan Brown"
                  ]  
                }
    put:
      description: Update book information.
      body:
         application/json:
          example: |  
            {
             "title": "Inferno",
             "isbn": "978-0-385-53785-8",
             "authors": [
              "Dan Brown"
             ]
            }
      responses:
        204:
          description: |
            The book has been successfully updated.
        404:
          description: |
            Unable to find book with that identifier.
    delete:
      description: Remove book from the catalog.
      responses:
        204:
          description: |
            The book has been successfully removed.
        404:
          description: |
            Unable to find book with that identifier.

As you can see, the Book Store API have five services:

Learn more about HTTP Status

Platforms and Tools

  • Mulesoft provides an API Platform and APIkit.
  • raml2html, transform raml file to html.
  • jaxrs-to-raml, generate raml file to existing JAX-RS services. It has been updated today, JAX-RS 2.0 Asynchronous Responses is now supported!!!

There are more RAML projects here.

Resources

There are a lot of resources about REST, how to write a good API, some of them are:

Comments