RAML Patterns

Overview

The RAML Patterns Library makes your life easy since it contains a collection of commonly used and reusable RAML patterns. There are also SAP Hybris-specific patterns published there. You can quickly build consistent APIs by using these patterns in your RAML files. The patterns can be:

• RAML resource types
• RAML traits

Generate APIs

The API Generator generates Java code out of a RAML file definition, or from a file that references remote patterns. For that reason, SAP Hybris recommends using the RAML Patterns and the Service SDK Generator plug-in in conjunction with each other.

Access the Patterns

An index of available patterns is available at https://pattern.yaas.io/. In order to use the patterns, include the URL of the specific pattern in your RAML file definition. For example:

traits:
- !include https://pattern.yaas.io/v2/trait-paged.yaml

At the top of every YAML pattern, there is a comment indicating where to import it and how to use it in your RAML file. For more details about reusing existing patterns, refer to the Using The Patterns tutorial.

Merging information from several patterns

If you use several patterns at the same time, the responses or the headers are combined together according to the RAML 1.0 Scratchpad. The general rules are:

• The resource types, which are defined closer to the method in the inheritance tree, have precedence over other resource types.
• The traits which are used earlier in the is : [...] attribute have precedence over the traits which are used later.
• The traits have precedence over resource types.
• The parameters and responses defined directly on the method have precedence over anything else.

Example

For example, if you have two traits defined like the following:

- happy:
    responses:
      200:
      description: The request succeeded
        headers:
          happy:
            type: string
            description: This header value says why the resource is happy

- happyOrNotFound:
    responses:
      200:
        description: The resource has been retrieved successfully
         headers:
           happy:
             type: string
             description: This header value says why the resource is happy
      404:
        description: The resource has not been found

And a resource type defined like the following:

- animal:
    get:
      responses:
         200:
          headers:
            happy:
              type: boolean
              description: Returns true if the resource is happy

When you use all of them on your resource, like the following:

/squirrels/{squirrelId}:
  description: Returns a single squirrel
  type: animal
  is: [happy,happyOrNotFound]
  get:
    responses:
      200:
        headers:
          happy:
            type: integer
            description: The level of happiness

You might not be able to tell what the description is in your 200 response. You also might not be able to tell if the type of your happy header is string, boolean, or integer.

Resulting response codes

In the example above, the resource's final 200 response is The request succeeded, as defined in the happy trait. The resource also has the 404 error defined. Its definition is in the happyOrNotFound trait, because no 404 response was defined in the happy trait.

Resulting headers

In the example above, the happy header of the resource is of type integer, as it is defined directly on the resource. The description of the header, however, is defined in the happy trait, because the resource-level definition does not have a description specified.

If the method-level definition of the header is removed, then the happy header is of type string. If the line is: [happy,happyOrNotFound] is removed, then there is no description of the 200 response. The header is of type boolean, and it has the same description as the one described in the corresponding resource type definition.

Use the Patterns

To include RAML patterns, use the available RAML Patterns provided at https://pattern.yaas.io/, which are described here.

Traits

To include a trait, use the !include statement with the YAML file. For example:

traits:
 - !include https://pattern.yaas.io/v2/trait-paged.yaml
 - !include https://pattern.yaas.io/v1/trait-sortable.yaml

To mark methods of collection resources as paged, include the trait-paged.yaml trait. For example:

traits:
 - !include https://pattern.yaas.io/v2/trait-paged.yaml

The pattern used at the method level looks similar to the following:

 /myResources:
   get:
     is: [ paged ]

Resource types

To include a resource type, use the resource-type-collection YAML file. For example:

resourceTypes:
 - !include https://pattern.yaas.io/v1/resource-type-collection.yaml

Usage of the resource type:

 /items
   type: collection

Security schema

To include the security schema, include the example RAML file content:

securitySchemes:
 - !include https://pattern.yaas.io/v1/security-schema-basic.yaml

To enable the basic authorization and authentication, include a security-schema-basic.yaml security schema. For example, import the following:

securitySchemas:
 - !include https://pattern.yaas.io/v1/security-schema-basic.yaml

To secure a resource:

 Securing a resource:

 /myResource
   securedBy: [ basic_auth ]

To secure a method:

 /myResource
  get:
   securedBy: [ basic_auth ]

Schemas

There are two ways to use a schema in your RAML definition:

1. Include it as an official schema definition, and use it in several places in the RAML definition. (recommended)
2. Use the schema directly without defining it as a schema in the RAML definition itself.

The recommended method is to include it as an official schema definition. For example, import the following:

schemas:
 - error: !include https://pattern.yaas.io/v1/schema-error-message.json

Use it like this:

 /items
   get:
     responses:
       500:
         body:
           application/json
             schema: error

You can also use the schema directly without defining it as a schema in the RAML definition itself, as shown in this example:

 /items
   get:
     responses:
       500:
         body:
           application/json
             schema: !include https://pattern.yaas.io/v1/schema-error-message.json