API Design using RAML 0.8

Gives overall picture about RAML 0.8 and its features related to API Design

Transcript

1. API Design in RAML 0.8 Author : Arun V S
2. RAML 0.8  RAML 0.8 is a YAML based language that describes RESTful APIs  RAML is a human-readable and machine process-able description of a RESTful API interface
3. Root Section  Defines common reference schemas  It contains API title, API Version, BaseURI, Media Type, Protocols and Schemas  Title (required) describes about an API  Version (optional) is included if multiple version of iteration are released  BaseUri is optional during development and required during deployment. It can be accessed as a service endpoint  Protocols (optional) is used to specify which protocol supported by an API (HTTP/HTTPS)
4. Root Section (Cntd.)  Media Type(optional) returned by API Responses and expected from API requests that accept body  Schemas (optional) specifies collections of schemas that could be used anywhere in the API definition
5. User Documentation  User Documentation (optional)  The API definition can include a variety of documents that serve as a user guides and reference documentation for the API.  Such documents can clarify how the API works or provide business context.
6. Resources and Nested Resource  Resources are identified by their relative URI, which must begin with a slash (/).  A resource defined as a root-level property is called a top-level resource  Its property's key is the resource's URI relative to the baseUri.  A resource defined as a child property of another resource is called a nested resource  Its property's key is its URI relative to its parent resource's URI.
7. Methods  In a RESTful API, methods are operations that are performed on a resource.  Common methods include  GET  POST  PUT  PATCH  DELETE  HEAD  OPTIONS
8. Methods  In a RESTful API, methods are operations that are performed on a resource.  Common methods include  GET  POST  PUT  PATCH  DELETE  HEAD  OPTIONS
9. Headers  An API's methods MAY support or require non-standard HTTP headers.  In the API definition, specify the non-standard HTTP headers by using the headers property.  The headers property is a map in which the key is the name of the header, and the value is itself a map specifying the header attributes
10. Body  Some method verbs expect the resource to be sent as a request body  A method's body is defined in the body property as a hashmap, in which the key MUST be a valid media type.  Resources CAN have alternate representations. For example, an API might support both JSON and XML representations
11. Schema  Responses MAY contain a description property that further clarifies why the response was emitted. Response descriptions are particularly useful for describing error conditions.  The value of the schemas property is an array of maps  The schema definitions MAY be included inline or by using the RAML !include user-defined data type.
12. Responses  Resource methods MAY have one or more responses  Responses MUST be a map of one or more HTTP status codes, where each status code itself is a map that describes that status code.  Each response MAY contain a body property, which conforms to the same structure as request body properties  Responses MAY contain a description property that further clarifies why the response was emitted. Response descriptions are particularly useful for describing error conditions.
13. Resource types and Traits  Describes the optional mechanism for using RAML resource types and traits to characterize resources so as to avoid unnecessary repetition in the RESTful API's definition.  A resource type is a partial resource definition that, like a resource, can specify a description and methods and their properties. Resources that use a resource type inherit its properties, such as its methods.  A trait is a partial method definition that, like a method, can provide method- level properties such as description, headers, query string parameters, and responses. Methods that use one or more traits inherit those traits' properties.
14. Security  Most REST APIs have one or more mechanisms to secure data access, identify requests, and determine access level and data visibility.  The securitySchemes property is declared at the API's root level.  The securitySchemes property MUST be used to specify an API's security mechanisms, including  required settings  authentication methods  describedBy  securedBy