Defining an example body payload and response for a RESTful API endpoint is an essential aspect of designing a modern API. These examples ensure that it is clear what the API contract expects to receive from the client and to respond with to the client.

In this post, I will highlight four ways to specify the expected incoming and outgoing body with examples.

Inline as body example

Explicitly include in the root RAML the example using the keyword example (singular) followed by the JSON or YAML representation of the example. See line 10 in the example below.

Include multiple examples of YAML/JSON

Reference a file that contains the example using the !include keyword. You must use the examples (plural) and name the examples uniquely. In this case the examples are named ex1 and ex2. See line 16/17 in the example below.

Include a single NamedExample RAML

Reference a NamedExample RAML file which defined the example in RAML format. You must use the examples (plural) keyword and can provide one or multiple examples. See line 22 in the example below.

Provide the example as a simple text message

Using the example (singular) keyword followed by a text message. See line 29 in the example below.

Full code snippet

The RAML code snippet below shows the four ways to add examples to you specification discussed above.

Five principles of RESTful API Design

There are five principal aspects to a RESTful API specification that must be considered prior to coding an API specification. Learn more with RESTful API Design.