Nav

To Design an API Specification (Visual Design)

Requires November 2017 Release

This procedure covers how to begin designing an API with the visual editing capabilities of Design Center. The following tasks are involved:

  • To design the RAML Root

  • To design a data type

  • To design a resource

  • To simulate calling the API in visual mode

  • To publish the API

The example API consumes the free online REST service JSONPlaceholder at http://jsonplaceholder.typicode.com. The oversimplified API just lists the comments that the service stores about a particular post. 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, this topic covers how design the API to return only the HTTP status code 200 when receiving a valid request.

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.

As you design an API, keep in mind that your design is set to 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.

design lock

To Design the RAML Root

  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 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, enter an API title to replace New API. For example, enter 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 Specify the id of the comment you want to retrieve.

  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, replace newBaseUriParameter with an arbitrary name. For example: Num.

    • 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 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 substitutes you can use for {num} in the URI. For example:

      • In Description, replace the default value Property description with a description of the Num property. For example, The id of stored comments in posts.

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

      • 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 Default Number, enter 1.

      • In Example number, enter 3.

      • Accept the other defaults.

        The generated RAML code appears in the RAML viewer as you make these entries.

        #%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 id of stored comments in posts
            default: 1
            type: integer
            required: false
        baseUri: http://jsonplaceholder.typicode.com/posts/{num}/

Next, design a data type.