Free MuleSoft CONNECT Keynote & Expo Pass Available!

Register now+
Nav

To Design a RAML API Specification (Code View)

Requires November 2017 Release

This procedure covers how to design a simple API that consumes the free online REST service JSONPlaceholder. The API has two resources: /users and /usersbyid. The API design supports requesting information about all users, or using an HTTP query parameter, requesting information about a particular user. In a real-world situation, you design the API to handle responses for all common HTTP status codes: 200, 400, 401, 404, 405, 406, and 415. For simplicity, you include code only for the HTTP status code 200 for receiving a valid request.

The complete code for this procedure to copy and paste appears at the end of this topic.

  1. In Anypoint Platform, click Design Center. Set up a project to create a new API specification:

    • In Projects, click Create. Select API Specification.

    • In New API Specification, type a name for your new project. For example, type placeholder. Click Create.

      The project opens for design in the master branch. In Design Center, a branch is a fork of a project that cannot be merged. Two lines of code based on the title and version of the API appear in the RAML editor.

  2. In the RAML editor, go to the next blank line (3).

    The possible entries you can make appear as options. Click to enter and correctly indent an option into the code.

    baseURI

    If you don’t see these options, click CTRL+space.

  3. At the root level, click Root > baseUri from the list of options. Enter http://jsonplaceholder.typicode.com.

  4. Go to the next line of code, and include a resource in the RAML. Indent the resource at the same level as the baseUri.

    For example, create a /users resource:

    ...
    baseUri: http://jsonplaceholder.typicode.com
    /users:
  5. Use auto-completion to enter the GET method to retrieve the information defined in http://jsonplaceholder.typicode.com.

    • Put your mouse pointer on the line below /users.

    • Indent one level.

    • Enter Ctrl+Space.

      get method
    • Select get.

  6. Add a description of the method on the next line. For example:

    /users:
      get:
        description: Retrieve a list of all the users
  7. Include HTTP responses in the RAML for simulating the API:

    responses:
          200:
            body:

    At this point, the API definition looks like this:

    #%RAML 1.0
    title: placeholder
    baseUri: http://jsonplaceholder.typicode.com
    /users:
      get:
        description: Retrieve a list of all the users.
        responses:
          200:
            body:
  8. Import a JSON example:

    • On your file system, create a user-example.json having the following content:

      [{
                    "id": 1,
                    "name": "Leanne Graham",
                    "username": "Bret",
                    "email": "Sincere@april.biz",
                    "address": {
                      "street": "Kulas Light",
                      "suite": "Apt. 556",
                      "city": "Gwenborough",
                      "zipcode": "92998-3874",
                      "geo": {
                        "lat": "-37.3159",
                        "lng": "81.1496"
                      }
                      },
                    "phone": "1-770-736-8031 x56442",
                    "website": "hildegard.org",
                    "company": {
                      "name": "Romaguera-Crona",
                      "catchPhrase": "Multi-layered client-server neural-net",
                      "bs": "harness real-time e-markets"
                    }
      }]
    • Click Files > Import.

      files import

    • Choose File or ZIP, and browse to and import the user-example.json file.

    • In Files, select the name of the API specification placeholder.raml to go back to the RAML code. In the RAML editor, type add the following lines to the code:

      ...
            application/json:
              example: !include user-example.json
  9. At one indentation from the root, define the following resource:

     /userbyid:
        get:
          description: Get information about a particular user
          queryParameters:
            id:
              description: Specify the id of the user you want to retrieve
              type:        integer
              required:    false
              example: 3
          responses:
            200:
              body:
                application/json:

    Define the response and example response for the GET method.

                  example: |
                    [{
                    "id": 3,
                    "name": "Clementine Bauch",
                    "username": "Samantha",
                    "email": "Nathan@yesenia.net",
                    "address": {
                      "street": "Douglas Extension",
                      "suite": "Suite 847",
                      "city": "McKenziehaven",
                      "zipcode": "59590-4157",
                      "geo": {
                        "lat": "-68.6102",
                        "lng": "-47.0653"
                      }
                    },
                    "phone": "1-463-123-4447",
                    "website": "ramiro.info",
                    "company": {
                      "name": "Romaguera-Jacobson",
                      "catchPhrase": "Face to face bifurcated interface",
                      "bs": "e-enable strategic applications"
                    } }]

RAML Code

The complete RAML code for this task is:

#%RAML 1.0
title: placeholder
version: 1.0
baseUri: http://jsonplaceholder.typicode.com
/users:
  get:
    description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:
            example: !include user-example.json
  /userbyid:
    get:
      description: Get information about a particular user
      queryParameters:
        id:
          description: Specify the id of the user you want to retrieve
          type:        integer
          required:    false
          example: 3
      responses:
        200:
          body:
            application/json:
              example: |
                [{
                "id": 3,
                "name": "Clementine Bauch",
                "username": "Samantha",
                "email": "Nathan@yesenia.net",
                "address": {
                  "street": "Douglas Extension",
                  "suite": "Suite 847",
                  "city": "McKenziehaven",
                  "zipcode": "59590-4157",
                  "geo": {
                    "lat": "-68.6102",
                    "lng": "-47.0653"
                  }
                },
                "phone": "1-463-123-4447",
                "website": "ramiro.info",
                "company": {
                  "name": "Romaguera-Jacobson",
                  "catchPhrase": "Face to face bifurcated interface",
                  "bs": "e-enable strategic applications"
                } }]

In this topic: