Let's take a quick look at the RAML file structure, which describes the RESTful web services. An RAML file is a text file with the recommended extension of .raml. It uses spaces as indentation; you can use two or four spaces for indentation. The details of the content that you will find in a typical RAML file are as follows. We are grouping the contents into different logical sections to keep this discussion simple and easy to follow:

• Basic information: An RAML file starts with the basic information of the RESTful web APIs that you want to describe. This information is listed in the root portion of the document. The basic information includes information about REST APIs, such as the API title, version, base URI, base URI parameters, and the data type definition for resources, protocols, and default media types. Optionally, the root portion can also include a variety of user documentation that serve as a user guide and reference documentation for the API. Such documentation details how the API works.
• Data types: RAML 1.0 adds the capability to define the data types that can be used to describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. The type definitions are not constrained with built-in data types; it allows custom data type definition as well. Also the !include tag can be used to import the external type definitions.
• Security: Mostly, the REST APIs that you see today are secure. You can have security scheme definitions for accessing APIs in the RAML file towards the beginning of the content, alongside the basic information.
• Resources and nested resources: The next step is to outline the resources and nested resources exposed via the REST APIs. Resources are identified by their relative URI. A nested resource (child resource) is a resource defined as the child of a parent resource. Nested resources are useful if you want to access a subset from a collection of resources (which is identified as the parent resource). The uriParameters property is used for describing the path parameter used for accessing the child resources.
• HTTP methods: Once you have all the RESTful resources defined in RAML, the next step is to define the HTTP methods, such as GET, POST, PUT, and DELETE, which a client can perform on resources:
  • Query parameters: If the REST resource method takes the query parameters, RAML lets you specify them along with HTTP methods via the queryParameters attribute, typically used with the HTTP GET method.
  • Request data: The request payload definition is also allowed in RAML. The request payload specifies the media type and form parameters present in the request, typically used with the HTTP PUT and POST methods.
  • Response: The definitions of the REST resource and the HTTP operations on them give a high-level overview of the REST APIs. However, to really consume these APIs in real life, the client application must be aware of the response codes and content type returned by the REST calls. RAML defines the response types for each resource method. This includes the HTTP status codes, descriptions, examples, or schemas.

Here is a simple RAML example. See the following JAX-RS resource method, which returns a Department object. Let's see how this JAX-RS resource can be represented in RAML:

@GET 
@Path("{id}") 
@Produces("application/json") 
public Department findDepartment(@PathParam("id") Short id){ 
    //Method body is omitted for brevity... 
} 

The RAML file describing the preceding resource method will look like the following:

#%RAML 1.0 
title: department resource 
version: 1.0 
baseUri: "http://localhost:8080/hrapp/webresources" 
types: 
  department: !include schemas/department.xsd 
  department-jsonschema: !include schemas/department-jsonschema.json 
/departments:    
  get:     
  /{id}:  
    uriParameters:  
      id:  
        type: integer 
    get:  
      responses:  
        200:  
          body:  
            application/json:  
              type: department-jsonschema 
              example: !include examples/department.json