Nav

To Design a Resource

Requires November 2017 Release

This procedure builds on designing the RAML root and data type in visual design mode.

  1. In the navigation pane, click +Create.

  2. Select Resource.

  3. In the navigation pane, click /newResource.

    new resource
  4. Set options to define the resource:

    • Rename the resource from /newResource to /comments.

    • Select one or more HTTP methods. For this example, accept the default method GET. You want the API to get comments about posts from the service.

    • Click Documentation and describe the GET method. For example, type Get comments about posts.

    • Click Responses, and then click Add New Response.

    • In Status, accept the default 200-OK.

    • In Description, describe the status. For example, type Success, comments retrieved.

      response
  5. Click Add Body to add a example response.

    This is the kind of response you expect when you call the API.

  6. Click Details to expand the property area and set the following options:

    • In Media Type, accept the default application/json.

    • In Type, select Object.

      The response that you are exemplifying consists of comments formatted as JSON objects.

  7. Click Details.

    details
  8. In Example, click Edit, and add the following code between the curly brackets:

      "userId": 1,
      "id": 1,
      "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
      "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita

The complete code for creating this API follows:

#%RAML 1.0
title: placeholder
version: development1
baseUri: http://jsonplaceholder.typicode.com/posts/{num}/
baseUriParameters:
  num:
    format: int
    type: integer
    minimum: 1
    maximum: 5
    example: 3
    description: The number of stored comments in posts
    default: 1
    required: false
/posts:
  get:
    description: Retrieve a list of posts
    responses:
      200:
        body:
          application/json:
            example: |
                  [
                    "userId": 1,
                    "id": 1,
                    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
                    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita
                  ]

Next, test the design by simulating a call to the API.

In this topic: