To Design a RAML API Specification
This procedure covers how to design an API that consumes the free online REST service JSONPlaceholder. The API has two resources:
/usersbyid. You can call the API to request information about all users, or using an HTTP query parameter, to request information about a particular user. You can download the example code for this procedure from the "Download" section at the end of this topic.
In Anypoint Platform, click Design Center. Set up a project to create a new API specification:
In Projects, click Create. Select API Specification.
In New API Specification, type a name for your new project. For example, type placeholder. Click Create.
The project opens for design in the master branch. Two lines of code based on the title and version of the API appear in the RAML editor.
In the RAML editor, go to the next blank line (3).
The possible entries you can make appear as options. Click to enter and correctly indent an option into the code.
If you don’t see these options, click .
At the root level, click Root > baseUri from the list of options. Enter
Go to the next line of code, and include a resource in the RAML. Indent the resource at the same level as the
For example, create a
... baseUri: http://jsonplaceholder.typicode.com /users:
Enter the GET method to retrieve the information defined in
http://jsonplaceholder.typicode.com. Put the method name followed by a colon on the lines below the resource name, indented one level. Indent and add a description on of the method on the next line. For example:
/users: get: description: Retrieve a list of all the users
Include HTTP responses in the RAML for simulating the API:
responses: 200: body:
At this point, the API definition looks like this:
#%RAML 1.0 title: placeholder baseUri: http://jsonplaceholder.typicode.com /users: get: description: Retrieve a list of all the users responses: 200: body:
user-example.jsonfrom the "Downloads" section of this document and create an include file of the JSON code:
Select Files > + > New File.
Select Other from the drop-down and name the file user-example.json. Click Submit.
The file at this point is empty.
Copy the contents of user-example.json and paste it into the editor:
In the RAML editor, type add the following lines to the code:
... application/json: example: !include user-example.json
At one indentation from the root, define the following resource:
/userbyid: get: description: Get information about a particular user queryParameters: id: description: Specify the id of the user you want to retrieve type: integer required: false example: 3 responses: 200: body: application/json:
Download the RAML code for this task, and add the example for the