Nav

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.

Files

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.

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

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.

baseURI

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

get method