Enterprise Java

RAML: Four ways to define examples

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.

Alex Theedom

Alex Theedom is a Senior Java Developer and has recently played a pivotal role in the architectural design and development of a microservice based, custom built lottery and instant win game platform. Alex has experience of Java web application development in a diverse range of fields including finance, e-learning, lottery and software development. He is the co-author of Professional Java EE Design Patterns and many articles.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button