Nav

To Design a RAML API Specification (Visual Design)

This procedure is one of four that cover how to design an API with visual editing capabilities of Design Center.

  • To design the RAML Root

  • To design a data type

  • To design a resource

  • To publish to Exchange and test the design

The example API consumes the free online REST service JSONPlaceholder at http://jsonplaceholder.typicode.com. The oversimplified API just lists the comments the service collects about a particular post.

To call the API, you enter the implementation URL of the API in a browser and add the ID of a post in the last component of the URL. Comments appear in the browser output.

To Design the RAML Root

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

    The branch enters read-only mode if you are idle for 10 minutes. Assuming nobody obtained the lock while you were idle, just click Edit to unlock and continue.

    locked branch
    • In Projects, click Create. Select API Specification.

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

    • Select Try API Designer’s Visual Editing Capabilities.

      vd new api
    • Click Create.

      Fields of RAML root properties appear for you to fill in.

      api info
  2. In API Summary, set options as follows:

    • In Title, accept the default or change the API title. For example, change the title to placeholder.

    • In Version, type a version of the API. For example, 0.1.

    • In Protocols, select HTTP or HTTPS. Select HTTP for this example.

    • In Media Type, select the format of the data the API returns. For example, select application/json.

    • In Base URI, type the following example URI:

      http://jsonplaceholder.typicode.com/posts/{num}/

      {num} is the base URI parameter that represents the ID of a post.

  3. In Description, type a description of API using markdown. For example, type This API gets the comments about a post given a variable integer post id at the end of the URL.

  4. Click Base URI Parameters.

    add base uri parameter
  5. Define the Num base URI parameter:

    • Click Add Base URI Parameter.

      Base URI Parameter Name and Type fields appear.

    • In Base URI Parameter Name, type an arbitrary name. For example: Num.

    • In Type, select a RAML scalar type. For example, select Integer.

    • In Base URI Parameters, click Details >.

      baseuri details

      Fill in the fields to define RAML facets that restrict what you can substitute for {num} in the URI. For example:

      • In Description, describe the Num property. For example, The number of stored comments in posts.

      • Change the default Required setting to unchecked. You do not want to require the user of the API to enter a parameter value. Instead, you will define a default in the event a parameter isn’t entered.

      • In Minimum and Maximum, enter input range limits. For example, type 1 and 5, respectively. To call the API, the parameter {num} must be a number between 1-5.

      • In Format, select a value. For example, select int.

      • In Example number, enter 3.

      • In Default Number, enter 1.

      • Accept the other defaults.

        The generated RAML code appears on the right.

        #%RAML 1.0
        title: placeholder
        description: This API gets the comments about a post given a variable integer post **id** at the end of the URL.
        version: '0.1'
        mediaType: application/json
        protocols:
          - HTTP
        baseUriParameters:
          Num:
            maximum: 5
            minimum: 1
            format: int
            example: 3
            description: The number of stored comments in posts
            default: 1
            type: integer
            required: false
        baseUri: http://jsonplaceholder.typicode.com/posts/{num}/

Next, design a data type.