### RAML Response Examples with Media Types

Source: https://github.com/raml-org/raml-spec/wiki/RAML™-Version-0.8:-RESTful-API-Modeling-Language

Illustrates defining GET responses in RAML, including specifying the media type for the response body and referencing example files.

```YAML
/media/popular:
  displayName: Most Popular Media
  get:
    description: |
      Get a list of what media is most popular at the moment.
    responses:
      200:
        body:
          application/json:
            example: !include examples/instagram-v1-media-popular-example.json

```

--------------------------------

### RAML Examples Syntax

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC1-vs-RC2

RC1 introduced a new syntax for defining multiple examples for types, allowing named examples within an `examples` block.

```YAML
types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples:
      acme: # Named example
        value: |
          {
            "name": "Acme Corporation",
            "address": "123 Main St"
          }
      beta:
        value: |
          {
            "name": "Beta Inc."
          }

```

--------------------------------

### RAML Query Parameters with Examples and Constraints

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

Illustrates enhanced query parameter definitions in RAML, including descriptions, requirements, default values, minimum/maximum constraints, and examples. Documentation generators use the 'example' attribute for invocation examples.

```yaml
#%RAML 0.8
title: GitHub API
version: v3
baseUri: https://api.github.com/{version}
/users:
  get:
    description: Get a list of users
    queryParameters:
      page:
        description: Specify the page that you want to retrieve
        type: integer
        required: true
        example: 1
      per_page:
        description: Specify the amount of items that will be retrieved per page
        type: integer
        minimum: 10
        maximum: 200
        default: 30
        example: 50
```

--------------------------------

### RAML Named Example Fragment Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates a RAML typed fragment file defining multiple NamedExamples for paging parameters. It includes examples for 'onlyStart' and 'startAndPageSize' with their respective values.

```yaml
#%RAML 1.0 NamedExample

#This file is located at examples/paging-examples.raml

onlyStart:
  displayName: Only Start
  value:
    start: 2
startAndPageSize:
  description: Contains start and page size
  value:
    start: 3
    page-size: 20

```

--------------------------------

### RAML Examples for Types, Bodies, and Headers

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates the usage of `example` and `examples` properties at various levels within a RAML API definition, including type declarations, request bodies, and response bodies.

```RAML
#%RAML 1.0
title: API with Examples

types:
  User:
    type: object
    properties:
      name: string
      lastname: string
    example:
      name: Bob
      lastname: Marley
  Org:
    type: object
    properties:
      name: string
      address?: string
      value?: string
/organizations:
  post:
    headers:
      UserID:
        description: the identifier for the user who posts a new organization
        type: string
        example: SWED-123 # single scalar example
    body:
      application/json:
        type: Org
        example: # single request body example
          value: # needs to be declared since instance contains a 'value' property
            name: Doe Enterprise
            value: Silver
/organizations/{orgId}:
  get:
    description: Returns an organization entity.
    responses:
      201:
        body:
          application/json:
            type: Org
            examples:
              acme:
                name: Acme
              softwareCorp:
                value: # validate against the available facets for the map value of an example
                  name: Software Corp
                  address: 35 Central Street
                  value: Gold # validate against an instance of the `value` property

```

--------------------------------

### RAML Multiple Examples Facet

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Shows how to define multiple named examples for a type declaration using the `examples` facet in RAML. Each example is a key-value pair, where the key is a unique identifier.

```yaml
message: # {key} - unique id
  # example declaration
  title: Attention needed
  body: You have been added to group 274
record: # {key} - unique id
  # example declaration
  name: log item
  comment: permission check
```

--------------------------------

### RAML 1.0 Bodies Property Example: Multiple Examples

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-scratchpad

Illustrates the `bodies` property in RAML 1.0, showcasing how to define a request body with a JSON schema and multiple named examples. Each example includes a description and the example payload.

```yaml
title: API with detailed bodies
/items:
  post:
    body:
      application/json:
        schema:
          type: json-schema/draft-04
          definition: |
            {
              "type": "object",
              "properties": {
                "name": {"type": "string"},
                "value": {"type": "integer"}
              }
            }
        examples:
          validItem:
            description: A valid item object.
            example: |
              {
                "name": "example",
                "value": 100
              }
          anotherValidItem:
            description: Another valid item.
            example: |
              {
                "name": "test",
                "value": 200
              }

```

--------------------------------

### RAML: Header Example Attribute

Source: https://github.com/raml-org/raml-spec/wiki/RAML™-Version-0.8:-RESTful-API-Modeling-Language

Shows how to include an 'example' attribute for headers in RAML. Documentation generators should use this to create example invocations, providing concrete values for header parameters.

```YAML
#%RAML 0.8
---
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
/jobs:
  post:
    description: Create a Job
    headers:
      Zencoder-Api-Key:
        description: |
          The API key for your Zencoder account. You can find your API key at
          https://app.zencoder.com/api. You can also regenerate your API key on
          that page.
        type: string
        required: true
        minLength: 30
        maxLength: 30
        example: abcdefghijabcdefghijabcdefghij
```

--------------------------------

### RAML: Query Parameter Example Attribute

Source: https://github.com/raml-org/raml-spec/wiki/RAML™-Version-0.8:-RESTful-API-Modeling-Language

Illustrates the use of the 'example' attribute for query parameters in RAML. Documentation generators must use this to create example invocations, providing concrete values for query parameters.

```YAML
#%RAML 0.8
---
title: GitHub API
version: v3
baseUri: https://api.github.com/{version}
/users:
  get:
    description: Get a list of users
    queryParameters:
      page:
        description: Specify the page that you want to retrieve
        type: integer
        required: true
        example: 1
      per_page:
        description: Specify the amount of items that will be retrieved per page
        type: integer
        minimum: 10
        maximum: 200
        default: 30
        example: 50
```

--------------------------------

### RAML Single Example Facet (Map with Facets)

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Shows how to use the `example` facet as a map to include additional metadata alongside the example value. This allows for `displayName`, `description`, annotations, and `strict` validation control.

```yaml
(pii): true
strict: false
value:
  title: Attention needed
  body: You have been added to group 274
```

--------------------------------

### RAML Basic Authentication Configuration Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

An example of how to configure Basic Authentication security schemes within a RAML file.

```yaml
#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  basic:
    description: |
      This API supports Basic Authentication.
    type: Basic Authentication
```

--------------------------------

### RAML Schema with Example Attributes

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

Illustrates how to provide example request bodies for specific media types alongside schema definitions in RAML. Documentation generators use these attributes for example invocations.

```YAML
/jobs:
  displayName: Jobs
  post:
    description: Create a Job
    body:
      text/xml:
        schema: !include job.xsd
        example: |
          <api-request>
            <input>s3://zencodertesting/test.mov</input>
          </api-request>
      application/json:
        schema: !include job.schema.json
        example: |
          {
            "input": "s3://zencodertesting/test.mov"
          }
```

--------------------------------

### RAML Single Example Facet (Explicit Value)

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates using the `example` facet to provide a single, explicit value for a type instance. This is a direct representation of the example data.

```yaml
title: Attention needed
body: You have been added to group 274
```

--------------------------------

### RAML Resource Type Fragment Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates a RAML typed fragment file defining a ResourceType. This fragment specifies properties for a collection resource, including descriptions for GET and POST methods, and response headers for POST.

```yaml
#%RAML 1.0 ResourceType

#This file is located at resourceTypes/collection.raml

description: A collection resource
usage: Use this to describe a resource that lists items
get:
  description: Retrieve all items
post:
  description: Add an item
  responses:
    201:
      headers:
        Location:
```

--------------------------------

### RAML API Including Named Example Fragment

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Presents a main RAML file that incorporates the NamedExample fragment. It defines a 'paging' type and associates the 'paging-examples.raml' fragment with the 'examples' facet of the query string for the '/products' resource.

```yaml
#%RAML 1.0
title: Products API

types:
  paging:
    properties:
      start?: number
      page-size?: number

/products:
  description: All products
  get:
    queryString:
      type: paging
      examples: !include examples/paging-examples.raml

```

--------------------------------

### RAML Query Parameter Specification

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Details the RAML syntax for defining query parameters in API endpoints. It covers parameter declarations, types, optionality (indicated by '?'), and how multiple instances of a parameter are handled. The example demonstrates a GET method with 'page' and 'per_page' query parameters.

```APIDOC
#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com/{version}
/users:
  get:
    description: Get a list of users
    queryParameters:
      page:
        description: Specify the page that you want to retrieve
        type:        integer
        required:    true
        example:     1
      per_page:
        description: Specify the amount of items that will be retrieved per page
        type:        integer
        minimum:     10
        maximum:     200
        default:     30
        example:     50
```

--------------------------------

### RAML Type and Example Syntax Evolution

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-RC1-vs-RC2

Illustrates changes in defining types and examples in RAML. RC1 used `content` with sequences, while RC2 introduced named examples and the `value` keyword for additional facets, aligning with broader specification consistency.

```APIDOC
#%RAML 1.0
types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    Examples: # using sequences w/o keys (ids)
      - content:
          name: Acme
      - content:
          name: Software Corp
          address: 35 Central Street
```

```APIDOC
#%RAML 1.0
types:
  Org:
    type: object
    properties:
      name: string
      address?: string
    examples:
      acme:
        name: Acme
      softwareCorp:
        value:
          name: Software Corp
          address: 35 Central Street
```

```APIDOC
#%RAML 1.0
example:
  height: 12
  width: 4
```

```APIDOC
#%RAML 1.0
example:
  (pii): true
  strict: false
  value:
    height: 12
    width: 4
```

--------------------------------

### RAML Pass Through Authentication Configuration Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

An example of how to configure Pass Through Authentication security schemes within a RAML file, including necessary headers and query parameters.

```yaml
#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  passthrough:
    description: |
      This API supports Pass Through Authentication.
    type: Pass Through
    describedBy:
      queryParameters:
        query:
          type: string
      headers:
        api_key:
          type: string
```

--------------------------------

### RAML Digest Authentication Configuration Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

An example of how to configure Digest Authentication security schemes within a RAML file.

```yaml
#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  digest:
    description: |
      This API supports DigestSecurityScheme Authentication.
    type: Digest Authentication
```

--------------------------------

### RAML Example API Definition

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

A basic RAML 1.0 API definition demonstrating the structure and syntax.

```RAML
#%RAML 1.0
title: Example API

```

--------------------------------

### RAML OAuth 1.0 Security Scheme Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

A complete RAML 1.0 example demonstrating the configuration of an OAuth 1.0 security scheme, including URIs and supported signature methods.

```yaml
#%RAML 1.0
title: My Sample API
securitySchemes:
  oauth_1_0:
    description: |
      OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
    type: OAuth 1.0
    settings:
      requestTokenUri: https://api.mysampleapi.com/1/oauth/request_token
      authorizationUri: https://api.mysampleapi.com/1/oauth/authorize
      tokenCredentialsUri: https://api.mysampleapi.com/1/oauth/access_token
      signatures: [ 'HMAC-SHA1', 'PLAINTEXT' ]

```

--------------------------------

### RAML OAuth 2.0 Configuration Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

An example of how to configure OAuth 2.0 security schemes within a RAML file, specifying authorization and token URIs, and supported grant types.

```yaml
#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  oauth_2_0:
    description: |
      Dropbox supports OAuth 2.0 for authenticating all API requests.
    type: OAuth 2.0
    describedBy:
      headers:
        Authorization:
          description: |
             Used to send a valid OAuth 2 access token. Do not use
             with the "access_token" query string parameter.
          type: string
      queryParameters:
        access_token:
          description: |
             Used to send a valid OAuth 2 access token. Do not use with
             the "Authorization" header.
          type: string
      responses:
        401:
          description: |
              Bad or expired token. This can happen if the user or Dropbox
              revoked or expired an access token. To fix, re-authenticate
              the user.
        403:
          description: |
              Bad OAuth request (wrong consumer key, bad nonce, expired
              timestamp...). Unfortunately, re-authenticating the user won't help here.
    settings:
      authorizationUri: https://www.dropbox.com/1/oauth2/authorize
      accessTokenUri: https://api.dropbox.com/1/oauth2/token
      authorizationGrants: [ authorization_code, implicit, 'urn:ietf:params:oauth:grant-type:saml2-bearer' ]
```

--------------------------------

### RAML Parameter Usage Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

This example demonstrates the definition and usage of parameters within RAML resource types and traits. It showcases reserved parameter names and the application of singularize/pluralize functions for parameter value transformation.

```YAML
#%RAML 0.8
title: Example API
version: v1
mediaType: application/json
schemas:
  - users: !include schemas/users.json
  - user: !include schemas/user.json
resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              schema: <<resourcePathName>> # e.g. users
      post:
        responses:
          200:
            body:
              schema: <<resourcePathName | !singularize>>  # e.g. user
  - member:
      get:
        responses:
          200:
            body:
              schema: <<resourcePathName>> # e.g. user
traits:
  - secured:
      description: Some requests require authentication
      queryParameters:
        <<methodName>>: # e.g. get:
          description: A <<methodName>> name-value pair must be provided for this request to succeed.  # e.g. A get name-value...
          example: <<methodName>>=h8duh3uhhu38   # e.g. get=h8duh3uhhu38

```

--------------------------------

### RAML Example Facet Properties

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Defines the properties available when using the `example` facet as a map. This includes `displayName`, `description`, custom annotations, the `value` itself, and a `strict` flag for validation.

```APIDOC
Example Facet Properties:

- displayName?: An alternate, human-friendly name for the example. If the example is part of an examples node, the default value is the unique identifier that is defined for this example.
- description?: A substantial, human-friendly description for an example. Its value MUST be a string and MAY be formatted using Markdown.
- (<annotationName>)? [Annotations]: Annotations to be applied to this API. An annotation MUST be a map having a key that begins with "(" and ends with ")", where the text enclosed in parentheses is the annotation name and the value is an instance of that annotation.
- value: The actual example of a type instance.
- strict?: Validates the example against any type declaration (the default), or not. Set this facet to false to avoid validation.
```

--------------------------------

### RAML Absolute URI Computation Example (GitHub API)

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

Explains the process of computing absolute URIs by concatenating the `baseUri` with the relative URIs of resources and nested resources. This example outlines the structure for the GitHub API.

```RAML
#%RAML 0.8
title: GitHub API
version: v3
baseUri: https://api.github.com
/user:
/users:
  /{userId}:
    uriParameters:
      userId:
        type: integer
    /followers:
    /following:
    /keys:
      /{keyId}:
        uriParameters:
          keyId:
            type: integer
```

--------------------------------

### RAML Request Body Examples

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Demonstrates defining request bodies for different media types (XML and JSON) within a RAML API specification, including schema and example payloads.

```YAML
/jobs:
  displayName: Jobs
  post:
    description: Create a Job
    body:
      text/xml:
        schema: !include job.xsd
        example: |
          <api-request>
            <input>s3://zencodertesting/test.mov</input>
          </api-request>
      application/json:
        schema: !include job.schema.json
        example: |
          {
            "input": "s3://zencodertesting/test.mov"
          }

```

--------------------------------

### RAML !include Tag Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates how to use the !include tag to import types from an external file (myTypes.raml) into the main RAML API definition.

```yaml
#%RAML 1.0
title: My API with Types
types: !include myTypes.raml
```

--------------------------------

### RAML 1.0 Library Definition Start

Source: https://github.com/raml-org/raml-spec/wiki/Breaking-Changes

Provides the initial structure for a RAML 1.0 Library definition, indicating a shift in how modularity and reusability are handled compared to RAML 0.8.

```yaml
#%RAML 1.0 Library


```

--------------------------------

### RAML Headers and Examples

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

Specifies how to define non-standard HTTP headers for API methods in RAML. This includes defining header attributes, supporting wildcard headers for custom data, and providing example values, types, and constraints.

```RAML
#%RAML 0.8
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
/jobs:
  post:
    description: Create a Job
    headers:
      Zencoder-Api-Key:
        displayName: ZEncoder API Key
```

```RAML
#%RAML 0.8
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
/jobs:
  post:
    description: Create a Job
    headers:
      Zencoder-Api-Key:
        displayName: ZEncoder API Key
      x-Zencoder-job-metadata-{*}:
        displayName: Job Metadata
        description: |
           Field names prefixed with x-Zencoder-job-metadata- contain user-specified metadata.
           The API does not validate or use this data. All metadata headers will be stored
           with the job and returned to the client when this resource is queried.
```

```RAML
#%RAML 0.8
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
/jobs:
  post:
    description: Create a Job
    headers:
      Zencoder-Api-Key:
        description: |
          The API key for your Zencoder account. You can find your API key at
          https://app.zencoder.com/api. You can also regenerate your API key on
          that page.
        type: string
        required: true
        minLength: 30
        maxLength: 30
        example: abcdefghijabcdefghijabcdefghij
```

--------------------------------

### RAML Dynamic !includes in Resource Types

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-scratchpad

Demonstrates how to use dynamic, parameter-driven !includes within resource types, allowing for flexible inclusion of external content like JSON examples based on resource properties.

```RAML
#%RAML 0.8
title: My Sample API
resourceTypes:
  - collection:
      get: {}
      post:
        body:
          example: !include <<resourcePathName!singularize>>.json
```

--------------------------------

### RAML Example: Protocols Specification

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Shows a RAML API definition specifying the supported protocols. This example indicates that the API can be accessed via both HTTP and HTTPS.

```YAML
#%RAML 0.8
---
title: Salesforce Chatter REST API
version: v28.0
protocols: [ HTTP, HTTPS ]
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

```

--------------------------------

### RAML Resource Structure Example

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Defines API resources and nested resources in RAML, showing how URIs are structured and how 'displayName' can be used for friendly naming.

```RAML
#%RAML 0.8
---
title: GitHub API
version: v3
baseUri: https://api.github.com
/gists:
  displayName: Gists
  /public:
    displayName: Public Gists
```

--------------------------------

### YAML Multi-value Simple Property Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates a 'Multi-value Simple Property' with a Sequence of YAML Scalars as its value.

```yaml
enum:
  - White
  - Black
  - Colored
```

--------------------------------

### RAML Security Scheme Declaration Example (YAML)

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

This example demonstrates how to declare security schemes in RAML, specifically for OAuth 2.0 and OAuth 1.0. It shows the structure for defining headers, query parameters, and error responses associated with these schemes.

```YAML
#%RAML 1.0
title: Dropbox API
version: 1
baseUri: https://api.dropbox.com/{version}
securitySchemes:
  oauth_2_0:
    description: |
      Dropbox supports OAuth 2.0 for authenticating all API requests.
    type: OAuth 2.0
    describedBy:
      headers:
        Authorization:
          description: |
             Used to send a valid OAuth 2 access token. Do not use
             with the "access_token" query string parameter.
          type: string
      queryParameters:
        access_token:
          description: |
             Used to send a valid OAuth 2 access token. Do not use with
             the "Authorization" header.
          type: string
      responses:
        401:
          description: |
              Bad or expired token. This can happen if the user or Dropbox
              revoked or expired an access token. To fix, re-authenticate
              the user.
        403:
          description: |
              Bad OAuth request (wrong consumer key, bad nonce, expired
              timestamp...). Unfortunately, re-authenticating the user won't help here.
    settings:
      authorizationUri: https://www.dropbox.com/1/oauth2/authorize
      accessTokenUri: https://api.dropbox.com/1/oauth2/token
      authorizationGrants: [ authorization_code, implicit ]
  oauth_1_0:
    description: |
      OAuth 1.0 continues to be supported for all API requests, but OAuth 2.0 is now preferred.
    type: OAuth 1.0
    settings:
      requestTokenUri: https://api.dropbox.com/1/oauth/request_token
      authorizationUri: https://www.dropbox.com/1/oauth/authorize
      tokenCredentialsUri: https://api.dropbox.com/1/oauth/access_token

```

--------------------------------

### RAML Library Definition Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

An example of a standalone RAML library document. It defines reusable constructs like data types ('File'), traits ('drm'), and resource types ('file'), showcasing how libraries promote modularity and externalize common API elements.

```YAML
#%RAML 1.0 Library
usage: |
  Use to define some basic file-related constructs.
types:
  File:
    properties:
      name:
      length:
        type: integer
traits:
  drm:
    headers:
      drm-key:
resourceTypes:
  file:
    get:
      is: [ drm ]
    put:
      is: [ drm ]

```

--------------------------------

### YAML Simple Property Type Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates 'Simple Properties' which have YAML Scalar or Sequence of Scalars as values.

```yaml
statusCode: 200
enum:
  - White
  - Black
  - Colored
```

--------------------------------

### RAML Trait Definition Example

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-scratchpad

Illustrates a basic trait definition in RAML, showcasing how traits can define reusable API components like headers and query parameters.

```yaml
#%RAML 0.8
title: My Sample API
traits:
  secured:
    headers:
      Authorization:
        description: Send this header with the secret token
        example: Bearer 71543fa6a11044b0a9f3a8354ddcb00e
  searchable:
    queryParameters:
      q:
        description: The search string

```

--------------------------------

### YAML Single-value Simple Property Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates a 'Single-value Simple Property' with a YAML Scalar value.

```yaml
statusCode: 200
```

--------------------------------

### Example XML Serialization Output

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Shows the resulting XML structure generated from the RAML type declaration that includes `xml` node configurations for attributes and wrapping.

```XML
<Person fullname="John Doe">
  <addresses>
     <Address>…</Address>
     ...
  </addresses>
</Person>

```

--------------------------------

### YAML Object Property Type Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates an 'Object Property' where the property's value is an Object.

```yaml
properties:
  statusCode: 200
  responseParameters:
    type: object
    description: "some description"
```

--------------------------------

### RAML Type Expression Examples

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates the usage of RAML type expressions in defining API schemas, including simple types, arrays, unions, and type aliases.

```YAML
#%RAML 1.0
title: My API With Types

types:
  Phone:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfSIMCards:
        type: number
  Notebook:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfUSBPorts:
        type: number
  Person:
    type: object
    properties:
      devices: ( Phone | Notebook )[]
      reports: Person[]

```

```YAML
#%RAML 1.0
title: My API With Types
types:
  Phone:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfSIMCards:
        type: number
  Notebook:
    type: object
    properties:
      manufacturer:
        type: string
      numberOfUSBPorts:
        type: number
  Devices:
    type:  ( Phone | Notebook )[]

```

--------------------------------

### RAML Annotation Types and Usage Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

This example demonstrates how to declare custom annotation types in RAML 1.0, including simple types, optional types, and types with properties and patterns. It also shows the application of these annotations to resources and methods within an API definition.

```YAML
#%RAML 1.0
title: Illustrating annotations
mediaType: application/json
annotationTypes:
  deprecated: nil
  experimental: nil | string
  feedbackRequested: string?
  testHarness:
    type: string # This line can be omitted as it's the default type
  badge:         # This annotation type allows string values, too
  clearanceLevel:
    properties:
      level:
        enum: [ low, medium, high ]
        required: true
      signature:
        pattern: "\\d{3}-\\w{12}"
        required: true
/groups:
  (experimental):
  (feedbackRequested):
/users:
  (testHarness): usersTest
  (badge): tested.gif
  (clearanceLevel):
    level: high
    signature: 230-ghtwvfrs1itr
  get:
    (deprecated):
    (experimental):
    (feedbackRequested): Feedback committed!
    responses:
      200:

```

--------------------------------

### RAML API Body Definitions and Referencing

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-scratchpad

Demonstrates how to define reusable bodies in RAML and reference them across resources and resource types. This includes defining schemas and examples for different body types.

```YAML
title: My Sample API
defaultMediaType: application/json
bodies:
  user:
    schema:
      type: json-schema/draft-03
      definition: | 
        {}
    examples:
      adminUser:
        description: An `admin` user has the `admin` property set to `true` and has the `allowed-operations` collection populated with the all the actions it can perform
        example: | 
          { an example of the JSON here }
      normalUser:
        description: A `normal` user does not have the `admin` property turned on.
        example: | 
          { an example of the JSON here }
  users:
    schema:
      type: json-schema/draft-03
      definition: | 
        {}
    example: | 
      { an example of the JSON here }
resourceTypes:
  collection:
    post:
      body: <<resourcePathName!singularize>>
    get:
      body: <<resourcePathName>>
/users:
  type: collection
  /me:
    get:
      responses:
        200:
          body: user

```

--------------------------------

### RAML Annotation Usage Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates how to define and apply custom annotations to different parts of a RAML API specification, such as resources, methods, and type declarations.

```yaml
#%RAML 1.0
title: Illustrating allowed targets
mediaType: application/json
annotationTypes:
  meta-resource-method:
    allowedTargets: [ Resource, Method ]
  meta-data:
    allowedTargets: TypeDeclaration
types:
  User:
    type: object
    (meta-data): on an object; on a data type declaration
    properties:
      name:
        type: string
        (meta-data): on a string property
/users:
  (meta-resource-method): on a resource
  get:
    (meta-resource-method): on a method
    responses:
      200:
        body:
          type: User[]
          (meta-data): on a body
```

--------------------------------

### RAML Example: Base URI with Version Parameter

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Illustrates a RAML API definition including a version property and a baseUri that utilizes a template parameter for the version. This is a common pattern for versioned APIs.

```YAML
#%RAML 0.8
---
title: Salesforce Chatter REST API
version: v28.0
baseUri: https://na1.salesforce.com/services/data/{version}/chatter

```

--------------------------------

### Define a RAML 1.0 API Endpoint

Source: https://github.com/raml-org/raml-spec/blob/master/README.md

This snippet demonstrates the basic structure of a RAML 1.0 API definition. It includes defining a resource path, an HTTP GET method, and a 200 OK response with a JSON body schema and example.

```yaml
#%RAML 1.0
title: Hello world # required title

/greeting: # optional resource
  get: # HTTP method declaration
    responses: # declare a response
      200: # HTTP status code
        body: # declare content of response
          application/json: # media type
            # structural definition of a response (schema or type)
            type: object
            properties:
              message: string
            example: # example how a response looks like
              message: "Hello world"
```

--------------------------------

### RAML: Restrict Additional Properties with Regex Patterns

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates how to restrict additional properties using regular expression patterns within the `additionalProperties` facet. This example defines a pattern property that matches keys starting with 'note' followed by digits.

```RAML
#%RAML 1.0
title: My API With Types
types:
  Person:
    properties:
      name:
        required: true
        type: string
      age:
        required: false
        type: number
      /^note\d+$/: # restrict any properties whose keys start with "note"
                   # followed by a string of one or more digits
        type: string
```

--------------------------------

### RAML Root Section Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates a basic RAML API definition including title, version, base URI, media type, security schemes, types, resource types, traits, and a root resource.

```yaml
#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
securitySchemes:
  oauth_2_0: !include securitySchemes/oauth_2_0.raml
types:
  Gist:  !include types/gist.raml
  Gists: !include types/gists.raml
resourceTypes:
  collection: !include types/collection.raml
traits:
 securedBy: [ oauth_2_0 ]
/users:
  type: collection
  get:
```

--------------------------------

### RAML Resource Properties - Display Name and Description

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md

Explains the use of 'displayName' for friendly resource naming and 'description' for providing brief explanations of API resources. These are optional but recommended for clarity.

```RAML
#%RAML 0.8
title: Example API
baseUri: https://example.com/api
/users:
  displayName: User Management
  description: API endpoints for managing user accounts.
  /users/{userId}:
    displayName: Specific User
    description: Operations for a single user identified by userId.
```

--------------------------------

### RAML 0.8 Trait Composition Example

Source: https://github.com/raml-org/raml-spec/wiki/Breaking-Changes

Shows an example of defining external traits in a separate file ('traits.raml') and composing them within an API definition in RAML 0.8.

```yaml
#%RAML 0.8
title: Pagination API

traits:
  - !include traits.raml # composing with includes from traits.raml
  - otherTrait: # explicit trait definition
      description: just another trait
```

--------------------------------

### Invalid Namespace Chaining Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

This example illustrates an invalid RAML fragment where namespace chaining is attempted by referencing 'files.file-type.File'. RAML does not permit chaining namespaces in this manner.

```yaml
#%RAML 1.0 ResourceType
# Invalid RAML Fragment
uses:
  files: libraries/files.raml
get:
  is: [ files.drm ]
  responses:
    200:
      body:
        application/json:
          type: files.file-type.File # invalid - no chaining allowed
```

--------------------------------

### RAML Example: Default Media Type

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Presents a RAML API definition where a default media type is set for requests and responses. This example specifies that the API exclusively uses application/json.

```YAML
#%RAML 0.8
---
title: Stormpath REST API
version: v1
baseUri: https://api.stormpath.com/{version}
mediaType: application/json

```

--------------------------------

### RAML: Applying Resource Types and Traits

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates the basic application of resource types and traits in RAML. Shows how to inherit properties and behaviors from defined types and traits to structure API resources.

```yaml
#%RAML 1.0
title: Example API
version: v1
resourceTypes:
  collection:  !include resourceTypes/collection.raml
  member:      !include resourceTypes/member.raml
traits:
  secured:     !include traits/secured.raml
  paged:       !include traits/paged.raml
  rateLimited: !include traits/rate-limited.raml
/users:
  type: collection
  is: [ secured ]
  get:
    is: [ paged, rateLimited ] # this method is also secured
  post:                        # this method is also secured

```

--------------------------------

### RAML Example: Basic API Definition Structure

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

This RAML snippet illustrates the fundamental structure of an API definition, including root section properties like title, version, base URI, and schema references. It provides a template for defining an API's metadata and resources.

```YAML
#%RAML 0.8
---
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
schemas:
  User:  schema/user.json
  Users: schema/users.json
  Org:   schema/org.json
  Orgs:  schema/orgs.json
```

--------------------------------

### RAML Example: Explicit Base URI Parameter

Source: https://github.com/raml-org/raml-spec/wiki/RAML&trade;-Version-0.8:-RESTful-API-Modeling-Language

Demonstrates how to declare an explicit base URI parameter in a RAML definition. This example shows a baseUri with a placeholder for a bucket name, which is then defined in the baseUriParameters section.

```YAML
#%RAML 0.8
---
title: Amazon S3 REST API
version: 1
baseUri: https://{bucketName}.s3.amazonaws.com
baseUriParameters:
  bucketName:
    description: The name of the bucket

```

--------------------------------

### RAML Multiple Inheritance Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Demonstrates how RAML supports multiple inheritance by listing parent types in a sequence. This example shows the `Teacher` type inheriting properties from both `Person` and `Employee` types.

```yaml
types:
  Person:
    type: object
    properties:
      name: string
  Employee:
    type: object
    properties:
      employeeNr: integer
  Teacher:
    type: [ Person, Employee ]
```

--------------------------------

### RAML Overlay and Extension Application Process

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Outlines the sequential process for applying multiple RAML overlays and extensions to a master API definition. This involves applying each extension/overlay to the result of the previous step, with validation for overlays after each application.

```APIDOC
1. Apply first overlay/extension to master RAML document.
2. Apply second overlay/extension to the modified API definition.
3. Repeat for all overlays/extensions.

Rules:
- Resolve !include tags before merging.
- Validate overlay restrictions after each overlay application.
- Apply inheritance of types, resource types, traits, and annotation types.
```

--------------------------------

### RAML 1.0 CORS Example: POST method CORS enabled

Source: https://github.com/raml-org/raml-spec/wiki/RAML-1.0-scratchpad

An example demonstrating how to enable CORS for a specific `POST` method on the `/users` resource in RAML 1.0. The `cors` property is configured at the resource level to allow requests from any origin (`*`).

```yaml
title: My sample API
/users:
  cors:
    allow-origin: *
  post:

```

--------------------------------

### RAML: Union Type Validation Example

Source: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

Illustrates how an instance of a union type is validated. An instance is considered valid if it meets the restrictions of at least one of its super types. The example shows a CatOrDog union type.

```RAML
types:
  CatOrDog:
    type: Cat | Dog # elements: Cat or Dog
  Cat:
    type: object
    properties:
      name: string
      color: string
  Dog:
    type: object
    properties:
      name: string
      fangs: string
```

```YAML
CatOrDog: # follows restrictions applied to the type 'Cat'
  name: Musia,
  color: brown
```