DEFINE SECURITY IN RAML

RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful or practically-RESTful APIs. RAML isn't strict: for now, it focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, RESTful constraints. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more. Basic Structure, defining Request and response are explained deeply in RAML 100 docs. RAML also allows you to define the security that would be used for the API

WHY SECURITY IN RAML?

API’s are defined to expose the data to outside world. Basically accessing the underlying, may be sensitive, data. While accessing the data security is one of the critical pieces that a API designer and developers should keep in mind. Since the data being retrieved by the API could be anything, the security becomes important and increases the confidence on the API.

HOW SECURITY IN RAML?

RAML, as we know is a documentation written as text or when using with Mule we could use the AnyPoint platform to design and mule APIKit to develop the RESTful API’s. Defining security can be divided into two parts, Defining SecuritySchemas and setting security for a resources/resourceType or as a whole.

SecuritySchemas is an optional element in the RAML root. SecuritySchemas contains the definition of the security that would be used to secure the api and it its method. This element contains the name, description, type, describedBy, queryParameters. Lets take the example below

Explaining the example

1. [-oauth_2.0] : this would be the name for the security scheme. This would be used to refer across the RAML when telling about the security of the resource.
2. description : description for the security
3. type: type of security
4. describedBy : what parameters describe the security like headers, queryParams and responses, as to what happens if its invalid
5. settings : where to do for authorization etc.

USAGE

The securedBy attribute of RAML document root may be used to apply security schemes to every method of API. This specifies that all methods in the API (unless they have their own securedBy attribute) can be authenticated by any mentioned security scheme. Applying a security scheme to a method overrides whichever security scheme has been applied to the API as whole. To indicate that the method is protected using a specific security scheme, the method MUST be defined by using the securedBy attribute. The value assigned to the securedBy attribute MUST be a list of any of the security schemes previously defined in the securitySchemes property of RAML document root. To indicate that the method may be called without applying any security scheme, the method may be provided with securedBy attribute containing null as array component.