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.
Published on Java Code Geeks with permission by Alex Theedom, partner at our JCG program. See the original article here: RAML: Four ways to define examples Opinions expressed by Java Code Geeks contributors are their own. |
