The document discusses designing REST APIs using RAML (RESTful API Modeling Language). It explains that RAML allows for easy creation, design, and testing of REST APIs. It provides details on how to design a RAML file, including adding resources, methods, query parameters, and responses. The document gives an example of designing a GET method for a "/pheripherals" resource that retrieves records based on a required "ItemCode" query parameter and describes possible 200, 400, and 500 level responses.

1. Designing ReST APIs with
RAML
Venkatanarayana k

2. ReST is abbreviated as representational state transfer.
The ReST API lets us to interact with anything that can send an HTTP/HTTPS request.
ReST APIs are very easy to create and design.
It supports various methods like GET, POST, PUT, DELETE etc to perform various types of
operations.
GET - Retrieve the information defined in the request URI.
PUT - Replace the addressed collection. At the object-level, create or update it.
POST - Create a new entry in the collection. This method is generally not used at the
object-level.
DELETE - Delete the information defined in the request URI.

3. In Mule, we can create and design a ReST service various ways.
But, with the new specification of RAML, it became quite a easy task to create, design and test
our APIs as per our requirement.
Before we start, we will actually look into what RAML really is.
RAML helps us to manage the whole API lifecycle starting from it’s design, develop to
sharing,Mocking.
It is basically build on top of YAML for describing ReSTful APIs and provides all the information
to describe an API.

4. How can we design RAML for our RESTAPIs
?

5. RAML can be designed in API designer.
API Designer is a standalone/embeddable editor for RAML (RESTful API Modeling Language)
written in JavaScript using Angular.JS. By default, the editor uses an in-browser filesystem
stored in HTML5 Local storage.
API designer :- https://www.mulesoft.com/platform/api/api-designer
Login to Anypoint Cloud Hub : https://anypoint.mulesoft.com/login/#/signin
Click API Manager and Add new API.
With this tool/editor, we can design our APIs and test it there itself using a mock service with the
tool.

6. Designing RAML for REST API

7. The initial RAML file will contain ROOT section, which will describe the basic information of the API.
It includes API Title, API Version, BaseUri and all the BaseUri Parameters.
#%RAML 0.8 is the first line in the RAML and it describe the RAML version

8. Protocols :- The protocols property used to specify the protocols that an API supports. If the
protocols property is not specified, the protocol specified at the baseUri property is used.
Media Type :- The default media type returned by API responses, It can be overwrite by
specifying at Body of the response. This property is specified at the root level of the API
definition.
Both the above properties are optional though.

9. ADDING RESOURCES

10. Resource :- Resources are identified by their relative URI, which MUST begin with a slash (/).
Let’s add a resource say /pheripherals. So, we will have a resource named pheripherals which will also act
as a sub url of baseUri.
displayName :- The displayName attribute provides a friendly name to the resource and can be used by
documentation generation tools. This property is OPTIONAL.
description :- Each resource have a description that describe the resource. This property is OPTIONAL.

11. Adding Methods
Adding Query Parameters
Adding Response

12. get: Method defined under resource
/pheripherals.
To retrieve records, passing query parameter
ItemCode.
Described properties how an input
parameter Itemcode should be
type: string  It should be a string type.
required: true  specifying this parameter is
mandatory.
minLength: 4  should search at least with
4 characters

13. responses:  list of responses for a
method.
Reponses would be
2_ _ (200 series) : OK in the case of
success
4_ _(400 series) : Bad request if a
unsupported content type is requested, or
for any other invalid request
5_ _(500 series): Internal Server error
when something unexpected happens
during the request processing.
Refer Undistributed REST by Michael
Stowe.
body: describes return type of response
and structure of response.

14. CONTINUE IN RAML(PART2)