Nav

To Design a RAML API Specification

This procedure covers how to design an API that consumes the free online REST service JSONPlaceholder. The API has two resources: /users and /usersbyid. You can call the API to request information about all users, or using an HTTP query parameter, to request information about a particular user. You can download the example code for this procedure from the "Download" section 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. 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 down angle bracket.

  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. Enter the GET method to retrieve the information defined in http://jsonplaceholder.typicode.com. Put the method name followed by a colon on the lines below the resource name, indented one level. Indent and add a description on of the method on the next line. For example:

    /users:
      get:
        description: Retrieve a list of all the users
  6. 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:
  7. Download the user-example.json from the "Downloads" section of this document and create an include file of the JSON code:

    • Select Files > + > New File.

    • Select Other from the drop-down and name the file user-example.json. Click Submit.

      The file at this point is empty.

    • Copy the contents of user-example.json and paste it into the editor:

      raml example
    • In the RAML editor, type add the following lines to the code:

      ...
            application/json:
              example: !include user-example.json
  8. 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:
  9. Download the RAML code for this task, and add the example for the /userbyid resource.

In this topic: