Designing an API Reference

Requires November 2017 Release

Written in RAML, an API specification typically includes the following things:

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

    If you don’t have an implementation of the API and cannot provide a baseURI, you can still test the API using the mocking service baseURI described below.

  • 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

When you create an API specification or API fragment project, the following panels appear for building, simulating, and publishing the API or a portion of it:

  • Files

    Shows the file name <project name>.raml for RAML code.

  • RAML editor

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

  • RAML Documentation

    Displays the version, base URI, and supported protocols before you define the API. Displays data types, resources, and methods for simulating the API after you define the API.


Angle bracket icons (not shown) expand and contract the panels.

From the Files dropdown, you import RAML, OAS, ZIP files consisting of RAML and JSON files, and JSON files from your file system or from URLs. OAS is converted to RAML. From the .raml, select Rename or Delete to perform these operations on a single specification or fragment.

files import export

If your API is located behind a firewall that prevents inbound requests, the API is unreachable and you cannot simulate calling the API using the mocking service unless you bypass the proxy. To bypass the proxy, click API Behind A Firewall to toggle the option to yes.

Auto-completion of Code

In the RAML editor, you can trigger code suggestions to appear. In the RAML editor, go to a blank line in your code. The possible entries you can make appear as options. Click to enter and correctly indent the option.


Alternatively, enter CTRL+Space. If no suggestions appear, try indenting and trying again until suggestions appear.

get method

Extracting the Data Type

You can extract the type data from a RAML contract using raml-parser-2 TypeDeclaration called toXmlSchema() to validate an XML payload against a RAML type.

In visual design mode, this capability is exposed in Extract Data Type.

extract dt