Contact Us 1-800-596-4880
  1. Homepage
  2. API Manager (1.x)
  3. Gatekeeper Enhanced Security Reference
  4. API Designer

  5. To Design a Basic RAML API

To Design a Basic RAML API (API Manager)

This procedure covers how to connect to an online REST service and consume the service using the API Designer in API Manager 1.14.4. If you have APIs in API Manager and a subscription to API Manager and Analytics, you can use API Designer as your RAML editor as described in this procedure. For simplicity, the procedure describes an example API that has only one resource: user information. The JSONPlaceholder service returns requests for user information in JSON. This procedure assumes you have already set up the API by assigning a name and version number to it in API Manager.

  1. From the API Administration page, click the product version number, and on the API version details page, click Define API in API Designer.

    Several lines of code based on the title and version of the API you provided appears.

  2. Add the baseURI, users resource, and get method to the placeholder RAML example:

  3. At the root level, enter the optional baseUri and its value, the JSONPlaceholder URL: http://jsonplaceholder.typicode.com.

    baseUri: http://jsonplaceholder.typicode.com

  4. Go to the next line of code, and if necessary, click shelf icon to expand the shelf.

    If you don’t see the shelf icon, refresh the page.

  5. Click New Resource on the shelf to add lines of skeleton code at the cursor position. Include the resources in the RAML, formatting each resource as URI relative to the baseUri.

    For this example, the resource is /users.

    Use a forward slash followed by an arbitrary resource name and a colon to enter the /users resource in URI format, as shown in the following example:

    ...
baseUri: http://jsonplaceholder.typicode.com
/users:

  6. Enter the method associated with the resource:

    • For example, specify the GET method to retrieve the information defined in http://jsonplaceholder.typicode.com.

    • Indent the method name followed by a colon on the lines below the resource name.

      At this point the API definition looks like this:

      #%RAML 1.0
title: placeholder
version: 1.0.development
baseUri: http://jsonplaceholder.typicode.com
/users:
  get:
    description: Retrieve a list of all the users

  7. Include HTTP responses in the RAML for simulating the API. For example, include the JSON placeholder responses:

    • Enter the code on line after the description, aligned with the description as follows:

          description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:

    • Download the include file, user-example.json.

    • In API Designer, click Project > Import

    • In Import file, select the type of file to import from the drop-down: RAML, OAS file, OAS spec.

    • Use Choose File to browse to and select the file. For example, select user-example.json.

      user-example.json appears in the API Designer files panel.

  8. In the RAML code, declare an include file for use as the example:

    ...
      application/json:
        example: !include user-example.json

Download

See Also