Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Design using RAML 0.8

API Design using RAML 0.8

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

Arun V S

May 13, 2017
Tweet

More Decks by Arun V S

Other Decks in Education

Transcript

  1. 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
  2. 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)
  3. 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
  4. 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.
  5. 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.
  6. Methods  In a RESTful API, methods are operations that

    are performed on a resource.  Common methods include  GET  POST  PUT  PATCH  DELETE  HEAD  OPTIONS
  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. 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
  9. 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
  10. 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.
  11. 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.
  12. 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.
  13. 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