Nav

Using API Designer in Anypoint Platform

API Designer for the RESTful API Modeling Language (RAML) is a web-based editor for authoring RAML specifications.

API Designer supports the following specifications:

After designing the API to the RAML specification using API Designer, you can implement the API using an SDK, such as APIkit 3.8.1 and later, Osprey, or JAXRS-Codegen.

Prerequisites

To use API Designer in Anypoint Platform, you need the following accounts and roles:

  • An Anypoint Platform account

    If you do not have an account, sign up now. If you sign up for an account, you are given the Organization Administrators role.

  • A member of API Creators or Organization Administrators role

    If you are not a member of one of these roles, you cannot see the Add new API button that you use to access the API Designer.

Accessing API Designer

You can access API Designer in the following ways:

  • From Anypoint Platform, using the procedure in the next section

    You need an Anypoint Platform account. If you already have an account, you need to belong to the API Creators role to create an API definition in API Designer. If you don’t already have an account, sign up.

  • By downloading API Designer from Github and following instructions to run it locally or embed it in an app

Using Designer in Anypoint Platform

After signing into Anypoint Platform, follow these steps to access API Designer:

  1. Click API Manager.

    The API administration page appears, listing the names of all APIs you are authorized to use.

  2. Click Add new API.

    The Add API dialog appears.

  3. Enter the following required information, for example:

    • API name: placeholder

    • Version name: 1.0.development

  4. Click Add.

    The API version page appears.

  5. In API Definition, click Define API in API Designer.

    API Designer appears and is divided into three panels:

designing-your-api-c9fdd
  • Files panel

    Shows the default file name api.raml for RAML code. An asterisk precedes the file name to indicate unsaved content.

  • RAML editor panel

    Contains generated code: the default RAML version 1.0, the names of the API, and the API version, which you provided to API Manager.

  • API Console

    For simulating the API, this panel displays data types, resources, and methods in your API. Until you define the API, the Console displays an empty Resources list. Turn on the Mocking Service on the top, right-hand side to simulate calls to the API.

The files panel lists names of any imported files, such as examples, that you can reference as include files. From the context menu, you can save, rename, and delete a file.

The RAML editor includes the following functions:

  • Checks and highlights syntax.

  • Flags incorrect syntax.

  • Displays a shelf of hints that you can click to insert the next line of code.

In the RAML Editor, you can hover over a red x problem indicator to see a hint about the problem. For example, an indicator says that the api.raml file has not yet been saved:

designing-your-api-d02b0

Creating an API Designer Project

Select Project > New File to select the RAML spec version and type of content you plan to include in the .raml file.

designing-your-api-d8129

Saving, Importing, and Exporting Files

Select Save from the Project menu to save the file and extinguish the problem indicator.

designing-your-api-e95e2

From the Project menu, you also select functions for creating a new file and folder, saving all files, importing a single, or multiple zipped RAML, OAS, or OAS specifications. You can also use Project > Import to import files having extensions other than .raml, such as user-examples.json.

You can compress and export all API Designer project files to an external location.

To export files multiple files:

  1. Click Project > Export files.

  2. In the export files dialog, name the zip file.

  3. Check Prevent this page from creating additional dialogs to overwrite this zip file on subsequent export operations.

    Alternatively, accept the default unchecked to create additional files on subsequent export operations.

  4. Click OK.

    API Designer zips and exports the file or files in the project to the default download location.

You can use a ZIP file that you export from API Designer in the following ways:

  • Import the zip file back into API Designer.

  • Import the zip file into Anypoint Studio 6.x.

Changing API Designer Background Color

From the View menu, you can toggle the black/white background color of API Designer.

designing-your-api-e62b3

Getting Help

From the Help menu, you can go to API Designer documentation or report a bug.

designing-your-api-dff70

Saving, Renaming, and Deleting a Single File

You right-click a file in the files panel and select Save, Rename, or Delete to perform these operations on a single file. The asterisk that indicates an unsaved file in the files panel, disappears. The error indicator in RAML editor about the unsaved file also disappears.

designing-your-api-53d84

To save all files in the project, click Project > Save All.

Using Hints—​RAML Editor Shelf and Autocompletion

A RAML editor shelf appears at the bottom of API Designer when you click Toggle Shelf Visibility icon at the bottom of the RAML editor panel. Then, when you position the cursor on a valid line for making an entry in the Editor, the shelf displays a list of elements. Click an element to enter its code. Categories of elements are Root, Docs, Parameters, Security, Resources, Traits and Types, Schemas, and Others.

designing-your-api-d8c97

When you place the cursor on a new line and in a different column of the editor, the appropriate elements appear on the shelf for you to click. Click the shelf icon to toggle visibility of the shelf.

API Designer makes suggestions as you type element names in the RAML editor panel. Select a suggestion to enter it into the editor.

designing-your-api-95304

Creating a RAML 1.0-based API

The API definition, written in RAML, includes the following things:

  • An optional baseURI node at the root of the RAML document

  • API resources, for example the collection of all customers or a specific customer

  • HTTP methods, such as GET, POST, PUT, and DELETE, allowed on each resource

  • The representation of the request and response messages for each method, such as GET /customer/1 → response: application/json.

Defining the baseURI

The baseURI node in the RAML definition is the endpoint URL where the actual API implementation (API proxy) is deployed. Configuring this URL does not deploy the API or guarantee that the API is accessible at that URL. You need to configure endpoints and deploy the API.

RAML API Example

This example, which connects to a free online REST service, JSONPlaceholder, uses RAML 1.0. You can download the example now. For simplicity, the example API has only one resource.

The JSONPlaceholder service returns requests for user information in JSON. The RESTful API interface navigates the JSON resource, and provides all user information to callers.

When the RAML editor opens, it generates three lines of code based on the title and version of the API you provided in the Add API dialog:


          
       
1
2
3
#%RAML 1.0
title: placeholder
version: 1.0.development

The first thing you do is add a baseURI to the code. The baseURI node in the RAML definition is the endpoint URL where the actual API implementation (API proxy) is deployed. Configuring this URL does not deploy the API or guarantee that the API is accessible at that URL. You need to configure endpoints and deploy the API.

To add the baseURI, users resource, and get method to the placeholder RAML example:

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

    The baseUri serves as an identifier for the API and forms the base of the URLs of the resources.

  2. 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:
  3. Enter the method associated with the resource.

    For this example, you need to 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

Including Example Responses

To include the HTTP responses in the placeholder RAML example:

  1. Enter responses: followed by the required response to the get method and the example. Indent these entries as shown in the following example.

    ...
        description: Retrieve a list of all the users
        responses:
          200:
            body:
              application/json:
                example: |
                  [{
                  "id": 1,
                  "name": "Leanne Graham",
                  "username": "Bret",
                  "email": "Sincere@april.biz",
                  "address": {
                    "street": "Kulas Light",
                    "suite": "Apt. 556",
                    "city": "Gwenborough",
                    "zipcode": "92998-3874",
                    "geo": {
                      "lat": "-37.3159",
                      "lng": "81.1496"
                    }
                  },
                  "phone": "1-770-736-8031 x56442",
                  "website": "hildegard.org",
                  "company": {
                    "name": "Romaguera-Crona",
                    "catchPhrase": "Multi-layered client-server neural-net",
                    "bs": "harness real-time e-markets"
                  } }]

    The response consists of a map of the HTTP status codes the API returns on success.

Using !include

To modularize the API definition, RAML provides several mechanisms, one of which is the  !include property. To keep the API definition concise, you can include external content, such as documentation, schemas, and frequently used patterns outside the definition itself. The parser interprets !include as if the content of the externally-hosted file or a URL were declared in-line.

To modify the placeholder RAML example to use an include file for the example responses:

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

  2. In API Designer, click Project > Import*, and choose user-example.json.

    The Import file dialog appears.

    designing-your-api-d3801
  3. Select the type of file to import from the drop-down: RAML, OAS file, OAS spec, and click 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.

  4. In the Files panel, right-click user-example.json, and select Save.

    Saving the include file you imported clears the error indicator.

  5. Remove the example code listed in the "Including Example Responses" section starting with example: |.

  6. Declare the an include file for use as the example:

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

Simulating Calls to the API in API Console

You can simulate calling the API in the API console. 

  1. Above the API console on the right, turn on the Mocking Service.

    In your RAML definition, the baseUri changes to a mocking service URI.

  2. In the API Console, click the GET tab.

    designing-your-api-35775

    Click Try it, then GET to return the example data.

    The user information in your example appears:

    [
       {
          "id": 1,
          "name": "Leanne Graham",
          "username": "Bret",
          "email": "Sincere@april.biz",
          "address": {
            "street": "Kulas Light",
            "suite": "Apt. 556",
            "city": "Gwenborough",
            "zipcode": "92998-3874",
            "geo": {
              "lat": "-37.3159",
              "lng": "81.1496"
            }
          },
          "phone": "1-770-736-8031 x56442",
          "website": "hildegard.org",
          "company": {
            "name": "Romaguera-Crona",
            "catchPhrase": "Multi-layered client-server neural-net",
            "bs": "harness real-time e-markets"
          }
        },
        ...

    Click Try it, and then GET to return the example data.

    The user informaiton in your example appears:

    [
       {
          "id": 1,
          "name": "Leanne Graham",
          "username": "Bret",
          "email": "Sincere@april.biz",
          "address": {
            "street": "Kulas Light",
            "suite": "Apt. 556",
            "city": "Gwenborough",
            "zipcode": "92998-3874",
            "geo": {
              "lat": "-37.3159",
              "lng": "81.1496"
            }
          },
          "phone": "1-770-736-8031 x56442",
          "website": "hildegard.org",
          "company": {
            "name": "Romaguera-Crona",
            "catchPhrase": "Multi-layered client-server neural-net",
            "bs": "harness real-time e-markets"
          }
        },
        ...
  3. Click the GET tab for the /userbyid resource. Click Try it, accept the default query parameter ID = 3, and click GET.

    The user information appears for the user having an ID 3.

You can download the completed example files.

Calling the Actual API

Instead of simulating the API, you can get the actual data from the JSONPlaceHolder service instead of the example data in your RAML.

  1. Turn the mocking service off in API Console.

  2. Save all files in the project.

  3. Configure a proxy and deploy the API to Cloudhub.

  4. Issue the following call to get the actual user list:

    http://placeholder.cloudhub.io/users

The actual user list from the JSONplaceholder site appears.

Adding Code for Policies

Depending on the policy you choose to apply to the API, the RAML definition of the API might need to include a security scheme. You can click a link on the Available Policies list on the API version details page to get any required RAML snippets.

designing-your-api-e1bdc

Importing an OAS 2.0 Specification

The capability to import an OAS 2.0 specification is at the beta stage of development in API Designer and not recommended for production usage. The following example shows how to import the Swagger pet store example.

To import an OAS 2.0 specification:

  1. Click Project > Import.

  2. In the Import file dialog, select OAS spec from the drop-down.

  3. In the text entry box, type http://petstore.swagger.io/v2/swagger.json.

  4. Click Import.

The Swagger pet store example appears in API Designer.