CODEWITHSUNDEEP
raml
Prasad
Prasad

Reputation: 1157

What is use of ?,! and <<>> in RAML

What is the use of ! in !include and ? in get?: and <<>> and also resourceTypes? I am not able to understand with examples provided either in the official website or some other websites? Can some explain with a clear example?

Upvotes: 0

Views: 4168

Answers (1)

Pedro
Pedro

Reputation: 1965

There's no use for "!" alone, the keyword "!include" includes the "!". I think the reason is to allow the use of the "include" word as a resource or in other parts of a RAML spec, without colliding with this keyword.

"?" marks the property as optional, a "get?" declares that method as optional in a resource type. "For example, a resource type declaration describes a body parameter that is used if the API defines a post method for that resource. Applying the resource type to a resource without a post method does not create the post method."

"<<>>" Double angle brackets enclose a parameter name in resource type and trait definitions. For example:

resourceTypes:
  rt:
    get:
      description: <<someParam>> 

/foo:
  type: { rt: { someParam: bar } }

That, will set a get method in resource "/foo", with the description "bar"

These can be used with any name, but there are 2 reserved keywords that are useful when defining resource types and traits, which are resourcePath and resourcePathName. resourcePath is the full resource URI relative to the baseUri if there is one. And resourcePathName is the rightmost of the non-URI-parameter-containing path fragments. For example for a resource "/groups/{groupId}", resourcePath will be exactly that and resourcePathName will be "groups". See the example bellow on how to use this.

Resource and method declarations are frequently repetitive, a Resource Type is a way of avoiding this repetition. If you have the same pattern for a group of resources, then you define a resource type "foo" and then declare the type of those resources as "foo".

In this example there are several resources which have a get method that retrieves all records of a type, and a post method that adds one of more records of a type:

types:
  books: !include types/books.raml
  persons: !include types/users.raml
  animals: !include types/animals.raml

resourceTypes:
  collection:
    get:
      description: get all <<resourcePathName>>
      responses:
        200:
          body:
            application/json:
              type: <<resourcePathName>>
   post:
     description: adds one or more <<resourcePathName>>
     body:
       application/json:
         type: <<resourcePathName>>

/books:
  type: collection
/persons:
  type: collection
/animals:
  type: collection

The key here is using <<resourcePathName>>, when on the /books resource, <<resourcePathName>> will return "books". And thus, will set the type of the get response and the type of the post request to books.

The same happens for the other 2 resources.

Upvotes: 3

Related Questions