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:
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 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.
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.
Before you turn on the mocking service to simulate calling the API, the API uses the baseURI value you specified, if any.
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.
The mocking service URI works only in the Design Center environment, You cannot go to
https://mocksvc.mulesoft.com/mocks/27e.../v1 using a client, such as Postman or a browser.