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 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:

    • Download the user-example.json from the "Downloads" section of this document and click Files > Import.

      files import

    • Choose RAML, and browse to and select the downloaded file.

    • 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:
  10. Download the RAML code for this task, and add the example for the /userbyid resource.

In this topic: