Designing an API Reference

Written in RAML, an API specification typically 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

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 URL, 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 or OAS specifications from files on 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.

Mocking Service baseURI

Before you turn on the mocking service to simulate calling the API, the API uses the baseURI value you specified, if any.

base uri http

After you turn on the mocking service, the mocking service base URI goes into effect. This URI is a proxy that Design Center needs to prevent the simulation from getting blocked by a same-origin restriction policy.

mocking uri

The mocking service URI works only in the Design Center environment, You cannot go to using a client, such as Postman or a browser.

In this topic: