Raml part 1

RAML Basics Part-1

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 t ype: 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)