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:
Shows the file name
<project name>.ramlfor RAML code.
Contains generated code: the default RAML version 1.0, the name of the API, and the API version that you provided to API Manager.
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.
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.
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.