RAML tutorial

• Design of API
• Writing the API in RAML using
  • Resources (/books)
  • Methods (GET, PUT, POST, DELETE)
  • URI Parameters ({bookTitle}) - object-based
  • Query parameters - for filtering collections
  • Responses

Resources

• Define various collections as resources

    - 3 resources (resources begin with / )
    ```
    /users:
        /authors:
        /books:
  

• Nested resources

    ```
    /authors:
        /{authorname}
    ```
  

• example:

    ```
     http://api.e-bookmobile.com/v1.0/authors/CJ_Date
  
    ```
  

  returns details about the author: CJ Date

Methods

• GET : Retrieve the info defined in the request-uri
• PUT : Replace the addressed collection - at Object-level, create/update it
• POST : Create a new-entry in the collection.

• DELETE : Delete the info defined in the request-uri

  • example:

    /books:
      get:
      post:
      put:
    

URI Parameters

• Allows to act upon more granular objects
  • Example: /authors are made up of individual authors {authoreName}
  • Are denoted by surrounding curly brackets

    /books:
      /{bookTitle}
    

• so far we have

  /books:
    get:
    put:
    post:
    /{bookTitle}:
        get:
        put:
        /author:
            get:
        /publisher:
            get:
  

Query Parameters

• Filter collections using specific attribute like rating or publicationYear
• Something that server requires to process the API (e.g accessToken)

/books:
    get:
        queryParameters:
            author:
            publicationYear:
            rating:
            isbn:
    put:
    post:
        queryParameters:
            accessToken:

Example: BookMobile API Design

#%RAML 1.0
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

/users:
    /authors:
        /{authorname}:
    /books
        get:
            queryParameters:
                author:
                publicationYear:
                rating:
                isbn:
        post:
        put:
        /{bookTitle}
            get:
            put:
            delete:
            /author:
                get:
            /publisher:
                get:

Responses

• Mapped to one or more HTTP status codes (like 200)

• Each response includes :

  • description
  • example

  • schemas ``` /books: /{bookTitle}: get:

      description: Retrieve a specific book title
      responses:
          200:
              body:
                  application/json:
                      example: |
                          {
                              data": {
                                  "id": "SbBGk",
                                  "title": "An introduction to Database Systems",
                                  "description": "The ultimate book for learning Database Systems" 
                                  "datetime": 1341533193,
                                  "genre": "Computer Science",
                                  "author": "C. J Date",
                                  "link": "http://e-bookmobile.com/books/Stiff",
                              },
                              "success": true,
                              "status": 200
    
                          }
    

```