RAML

https://raml.org
Admin
RAML (RESTful API Modeling Language) is a human-readable format for describing and modeling...
Tokens:75,932
Snippets:578
Trust Score:9.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Configure /songs Resource with Examples in RAML

Source: https://raml.org/developers/raml-200-tutorial

Configures the '/songs' resource in RAML, specifying its type as 'collection' and providing example values for 'exampleCollection' and 'exampleItem'. It also defines a GET query parameter 'songTitle'.

```yaml
/songs:
  type:
    collection:
      exampleCollection: |
        [
          {
            "songId": "550e8400-e29b-41d4-a716-446655440000",
            "songTitle": "Get Lucky"
          },
          {
            "songId": "550e8400-e29b-41d4-a716-446655440111",
            "songTitle": "Loose yourself to dance"
          },
          {
            "songId": "550e8400-e29b-41d4-a716-446655440222",
            "songTitle": "Gio sorgio by Morodera"
          }
        ]
      exampleItem: |
        {
          "songId": "550e8400-e29b-41d4-a716-446655440000",
          "songTitle": "Get Lucky",
          "albumId": "183100e3-0e2b-4404-a716-66104d440550"
        }
  get:
    queryParameters:
      songTitle:
        description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
        required: true
        minLength: 3
        type: string
        example: "Get L"
```

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

### GET /products

Source: https://raml.org/blogs/mocking-service-walkthrough

Retrieves a list of products from the catalog. The response includes an example list of products.

```APIDOC
## GET /products

### Description
Retrieves a list of products from the catalog. The response includes an example list of products.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **apiKey** (string) - Required - A unique API key for authentication.

### Request Example
```bash
curl -X GET \
  'http://your-mocked-api.com/products?apiKey=YOUR_API_KEY' \
  -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the product.
- **name** (string) - The name of the product.
- **price** (number) - The price of the product.

#### Response Example
```json
[
  {
    "id": 10,
    "name": "Diet Coke",
    "price": 5
  },
  {
    "id": 11,
    "name": "Diet Sprite",
    "price": 3
  },
  {
    "id": 12,
    "name": "Diet Fanta",
    "price": 3
  }
]
```
```

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

### Complete RAML Response with JSON Example

Source: https://raml.org/blogs/mocking-service-walkthrough

This RAML snippet illustrates how to define a complete response for the '/products' GET request. It includes a JSON body with an example array of product objects, enabling the Mocking Service to return structured data.

```RAML
#%RAML 0.8
title: Product Catalog API
version: 1.0

/products:
  displayName: Catalog of Products
  get:
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "id": 10,
                "name": "Diet Coke",
                "price": 5
              },
              {
                "id": 11,
                "name": "Diet Sprite",
                "price": 3
              },
              {
                "id": 12,
                "name": "Diet Fanta",
                "price": 3
              }


```

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

### Generate HTML documentation from RAML definition using raml2html

Source: https://raml.org/blogs/guest-post-api-first-raml-development-and-documentation-rest-apis

This command-line example shows how to generate HTML documentation from a RAML definition file using the 'raml2html' Node.js tool. It first installs the tool globally and then executes it to convert 'api.raml' into 'api.html'.

```bash
npm i -g raml2html
raml2html api.raml > api.html

```

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

### Define Basic RAML Resource and Empty Response

Source: https://raml.org/blogs/mocking-service-walkthrough

This snippet shows the initial RAML configuration for a product catalog API. It defines the '/products' resource and an empty GET response, demonstrating the starting point for mocking.

```RAML
#%RAML 0.8
title: Product Catalog API
version: 1.0

/products:
  displayName: Catalog of Products
  get:
    responses:
      200:

```

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

### cURL: Example of Mocked API GET Request

Source: https://raml.org/blogs/mocking-service-walkthrough

This cURL command demonstrates how to invoke a mocked API endpoint. It shows a basic GET request to the '/products' resource, which can be used to test the API's response without a live backend implementation.

```shell
curl -X GET https://your.api.base.uri/products
```

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

### Applying the Searchable Trait to a RAML Resource Method

Source: https://raml.org/developers/raml-200-tutorial

This snippet shows how to apply the previously defined 'searchable' trait to the GET method of the '/songs' resource in RAML. It demonstrates how to pass specific values for the trait's parameters, such as 'description' and 'example', to customize its behavior for this particular method.

```RAML
/songs:
  type:
    collection:
      exampleCollection: !include jukebox-include-songs.sample
      exampleItem: !include jukebox-include-song-new.sample
  get:
    is: [searchable: {description: "with valid searchable fields: songTitle", example: "[\"songTitle\", \"Get L\", \"like\"]"}]

```

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

### RAML Include Directive Example

Source: https://raml.org/developers/raml-200-tutorial

This RAML snippet demonstrates the use of the '!include' directive to incorporate external files into the main API definition. It shows how to include example files for a collection of songs and individual song items, promoting modularity and reusability.

```RAML
/songs:
  type:
    collection:
      exampleCollection: !include jukebox-include-songs.sample
      exampleItem: !include jukebox-include-song-new.sample
  /{songId}:
    type:
      collection-item:
        exampleItem: !include jukebox-include-song-retrieve.sample

```

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

### Install and Use RAML to HTML CLI

Source: https://raml.org/blogs/new-community-projects

This command-line interface installs globally and converts a RAML file into a single HTML documentation page. It has minimal dependencies, requiring only Bootstrap and jQuery. The output is a clean and smart HTML page.

```bash
npm i -g raml2html

raml2html example.raml > example.html
```

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

### RAML Basic Resource Structure

Source: https://raml.org/developers/raml-200-tutorial

This snippet demonstrates a fundamental RAML structure defining a resource '/resources' with associated HTTP methods (GET, POST, PUT, DELETE). It serves as a starting point for understanding resource definition in RAML.

```RAML
#%RAML 1.0
  title: 

  /resources:
    get:
    post:
    /{resourceId}:
      get:
      put:
      delete:

```

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

### Configure /songs/{songId} Resource with Item Details in RAML

Source: https://raml.org/developers/raml-200-tutorial

Configures the '/songs/{songId}' resource in RAML, specifying its type as 'collection-item' and providing a detailed example for 'exampleItem'. This example includes song, artist, and album information.

```yaml
/{songId}:
  type:
    collection-item:
      exampleItem: |
        {
          "songId": "550e8400-e29b-41d4-a716-446655440000",
          "songTitle": "Get Lucky",
          "duration": "6:07",
          "artist": {
            "artistId": "110e8300-e32b-41d4-a716-664400445500"
            "artistName": "Daft Punk",
            "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
          },
          "album": {
            "albumId": "183100e3-0e2b-4404-a716-66104d440550",
            "albumName": "Random Access Memories",
            "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
          }
```

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

### GET /artists

Source: https://raml.org/developers/raml-200-tutorial

Retrieves a collection of artists. Supports searching, ordering, and pagination.

```APIDOC
## GET /artists

### Description
Retrieves a collection of artists. Supports searching, ordering, and pagination.

### Method
GET

### Endpoint
/artists

### Parameters
#### Query Parameters
- **query** (string) - Optional - JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] with valid searchable fields: artistName
- **orderBy** (string) - Optional - Order by field
- **order** (string) - Optional - Order direction. Enum: [desc, asc]. Default: desc
- **offset** (integer) - Optional - Skip over a number of elements by specifying an offset value for the query

### Request Example
```json
{
  "example": "/artists?query=\"[\"artistName\", \"Queen\", \"like\"]\"&orderBy=name&order=asc&offset=10"
}
```

### Response
#### Success Response (200)
- **artists** (array) - An array of artist objects.

#### Response Example
```json
{
  "example": [
    {
      "id": "1",
      "name": "Queen"
    }
  ]
}
```
```

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

### GET /albums

Source: https://raml.org/developers/raml-200-tutorial

Retrieves a collection of albums. Supports searching, ordering, and pagination.

```APIDOC
## GET /albums

### Description
Retrieves a collection of albums. Supports searching, ordering, and pagination.

### Method
GET

### Endpoint
/albums

### Parameters
#### Query Parameters
- **query** (string) - Optional - JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] with valid searchable fields: albumTitle
- **orderBy** (string) - Optional - Order by field
- **order** (string) - Optional - Order direction. Enum: [desc, asc]. Default: desc
- **offset** (integer) - Optional - Skip over a number of elements by specifying an offset value for the query

### Request Example
```json
{
  "example": "/albums?query=\"[\"albumTitle\", \"A Night at the Opera\", \"like\"]\"&orderBy=title&order=asc&offset=10"
}
```

### Response
#### Success Response (200)
- **albums** (array) - An array of album objects.

#### Response Example
```json
{
  "example": [
    {
      "id": "1",
      "title": "A Night at the Opera",
      "artistId": "1"
    }
  ]
}
```
```

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

### Applying Collection Resource Type to /artists/{artistId}/albums

Source: https://raml.org/developers/raml-200-tutorial

This snippet demonstrates the application of the 'collection' resource type to the '/artists/{artistId}/albums' resource. It includes the definition for 'exampleCollection' and an empty 'exampleItem', highlighting the initial setup before addressing read-only sub-collections.

```RAML
/artists:
  /{artistId}:
    /albums:
      type:
        collection:
          exampleCollection: !include jukebox-include-artist-albums.sample
          exampleItem: {}
      description: Collection of albums belonging to the artist
      get:
        description: Get a specific artist's albums list

```

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

### POST /products

Source: https://raml.org/blogs/mocking-service-walkthrough

Creates a new product in the catalog. Requires a JSON payload with product details.

```APIDOC
## POST /products

### Description
Creates a new product in the catalog. Requires a JSON payload with product details.

### Method
POST

### Endpoint
/products

### Parameters
#### Request Body
- **name** (string) - Required - The name of the product.
- **price** (number) - Optional - The price of the product.

### Request Example
```json
{
  "name": "Coke",
  "price": 4
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the newly created product.
- **name** (string) - The name of the product.
- **price** (number) - The price of the product.

#### Response Example
```json
{
  "id": 100,
  "name": "Coke",
  "price": 4
}
```
```

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

### Define Responses in RAML

Source: https://raml.org/developers/raml-100-tutorial

This snippet shows how to define responses for API methods in RAML. It includes an example of a successful GET request for a specific book title, specifying the HTTP status code, content type, and a JSON example of the response body.

```RAML
/books:
  /{bookTitle}:
    get:
      description: Retrieve a specific book title
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "data": {
                    "id": "SbBGk",
                    "title": "Stiff: The Curious Lives of Human Cadavers",
                    "description": null,
                    "datetime": 1341533193,
                    "genre": "science",
                    "author": "Mary Roach",
                    "link": "http://e-bookmobile.com/books/Stiff"
                  },
                  "success": true,
                  "status": 200
                }

```

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

### GET /products

Source: https://raml.org/blogs/mocking-service-walkthrough

Retrieves a list of products from the catalog. Supports optional 'itemsCount' for pagination.

```APIDOC
## GET /products

### Description
Retrieves a list of products from the catalog. Supports optional 'itemsCount' for pagination.

### Method
GET

### Endpoint
/products

### Parameters
#### Query Parameters
- **itemsCount** (integer) - Optional - Specifies the number of items to return for pagination.

### Request Example
```
GET /products?itemsCount=10
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the product.
- **name** (string) - The name of the product.
- **price** (number) - The price of the product.

#### Response Example
```json
{
  "id": 10,
  "name": "Diet Coke",
  "price": 5
}
```
```

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

### Define Collection Resource Type in RAML

Source: https://raml.org/developers/raml-200-tutorial

Defines a 'collection' resource type in RAML, including GET and POST methods with descriptions, query parameters, and response examples. It uses placeholders like <<resourcePathName>> and <<exampleCollection>>.

```yaml
resourceTypes:
  collection:
    description: Collection of available <<resourcePathName>> in Jukebox
    get:
      description: Get a list of <<resourcePathName>> based on the song title.
      responses:
        200:
          body:
            application/json:
              example: <<exampleCollection>>
    post:
      description: |
        Add a new <<resourcePathName|!singularize>> to Jukebox.
      queryParameters:
        access_token:
          description: "The access token provided by the authentication application"
          example: AABBCCDD
          required: true
          type: string
      body:
        application/json:
          type: <<resourcePathName|!singularize>>
          example: <<exampleItem>>
      responses:
        200:
          body:
            application/json:
              example: | 
                { "message": "The <<resourcePathName|!singularize>> has been properly entered" }
  collection-item:
    description: Entity representing a <<resourcePathName|!singularize>>
    get:
      description: |
        Get the <<resourcePathName|!singularize>>
        with <<resourcePathName|!singularize>>Id = 
        {<<resourcePathName|!singularize>>Id}
      responses:
        200:
          body:
            application/json:
        404:
          body:
            application/json:
              example: | 
                {"message": "<<resourcePathName|!singularize>> not found" }
```

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

### RAML API Specification Example

Source: https://raml.org/enterprise/raml-news

This RAML 1.0 specification defines a Mobile Order API. It includes the API title, base URI, version, reusable types (using 'uses'), annotation types, and defines endpoints for '/orders' with GET and POST methods, and a sub-resource '/{orderId}' with a GET method. It also specifies query parameters, responses with different content types (JSON and XML), and includes an external XSD schema.

```raml
#%RAML 1.0
title: Mobile Order API
baseUri: http://localhost:8081/api
version: 1.0
uses:
  assets: assets.lib.raml
annotationTypes:
  monitoringInterval:
    type: integer
/orders:
  displayName: Orders
  get:
    is: [ assets.paging ]
    (monitoringInterval): 30
    description: Lists all orders of a specific user
    queryParameters:
      userId:
        type: string
        description: use to query all orders of a user
  post:
    /{orderId}:
      get:
        responses:
          200:
            body:
              application/json:
                type: assets.Order
              application/xml:
                type: !include schemas/order.xsd
```

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

### RAML Single Song Endpoint Definition

Source: https://raml.org/developers/raml-200-tutorial

Defines the '/songs/{songId}' endpoint for retrieving details of a specific song. It includes GET method definitions for fetching song information and its file content, along with example responses for success (200) and not found (404).

```RAML
/{songId}:
  description: Song entity
  get:
    description: Get the song with `songId = {songId}`
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "songId": "550e8400-e29b-41d4-a716-446655440000",
                "songTitle": "Get Lucky",
                "duration": "6:07",
                "artist": {
                  "artistId": "110e8300-e32b-41d4-a716-664400445500"
                  "artistName": "Daft Punk",
                  "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
                },
                "album": {
                  "albumId": "183100e3-0e2b-4404-a716-66104d440550",
                  "albumName": "Random Access Memories",
                  "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
                }
              }
      404:
        body:
          application/json:
            example: "{"message": "Song not found"}"
  /file-content:
    description: The file to be reproduced by the client
    get:
      description: Get the file content
      responses:
        200:
    post:

```

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

### Bluetooth Communication with Node.js

Source: https://raml.org/blogs/restful-robots-project

Example code demonstrating how to connect to a Bluetooth serial port using the 'bluetooth-serial-port' library in Node.js. It includes steps for discovering devices, connecting, and writing data.

```javascript
const BluetoothSerialPort = require('bluetooth-serial-port');
const btSerial = new BluetoothSerialPort.BluetoothSerialPort();

const robotAddress = 'B8-63-BC-00-12-16'; // Example address
const channel = 1; // Example channel

btSerial.findSerialPortChannel(robotAddress, function (channel) {
  if (channel === -1) {
    console.log('Robot not found.');
    return;
  }
  console.log('Found channel:', channel);
  btSerial.connect(robotAddress, channel, function (err) {
    if (err) {
      console.error('Connection error:', err);
      return;
    }
    console.log('Connected to robot.');

    // Create a binary packet (example: 'sit' command)
    // This needs to be constructed according to the packet structure documented elsewhere.
    const packet = Buffer.from([0xff, 0xff, 0xfd, 0x00, 0xc8, 0x07, 0x00, 0x03, 0x42, 0x00, 0x03, 0x00, 0xd9, 0xed]); // Example 'sit' packet

    btSerial.write(packet, function (err, bytesWritten) {
      if (err) {
        console.error('Write error:', err);
      } else {
        console.log('Sent', bytesWritten, 'bytes.');
      }
      btSerial.close();
    });
  });
});
```

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

### RAML: Define Product Catalog API with Query Parameters

Source: https://raml.org/blogs/mocking-service-walkthrough

This RAML definition sets up a Product Catalog API with a GET endpoint for '/products'. It includes a query parameter 'itemsCount' of type integer, demonstrating data type validation. The response for a 200 status includes a JSON body with product examples.

```RAML
#%RAML 0.8
title: Product Catalog API
version: 1.0

/products:
  displayName: Catalog of Products
  get:
    queryParameters:
      itemsCount:
        required: false
        type: integer
    responses:
      200:
        body:
          application/json:
            example: |
             {
                "id": 10,
                "name": "Diet Coke",
                "price": 5
              },
              {
                "id": 11,
                "name": "Diet Sprite",
                "price": 3
              },
              {
                "id": 12,
                "name": "Diet Fanta",
                "price": 3
              }


```

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

### Bluetooth Communication with Node.js

Source: https://raml.org/blogs/restful-robots-project

Example code demonstrating how to connect to a Bluetooth device and send data using the 'bluetooth-serial-port' library in Node.js. This involves discovering devices, connecting to a specific device by its address and channel, and writing binary data to the serial port. This is the core logic for controlling the robot wirelessly.

```javascript
const BluetoothSerialPort = require('bluetooth-serial-port');
const btSerial = new BluetoothSerialPort.BluetoothSerialPort();

const robotAddress = 'B8-63-BC-00-12-16'; // Example address
const channel = 1; // Example channel

btSerial.findSerialPortChannel(robotAddress, function(channel) {
  if (channel === -1) {
    console.log('Robot not found.');
    return;
  }
  console.log('Found channel:', channel);
  btSerial.connect(robotAddress, channel, function() {
    console.log('Connected to robot.');

    // Create and send a command packet
    const commandPacket = Buffer.from('ff ff fd 00 c8 07 00 03 42 00 03 00', 'hex'); // Example 'sit' command
    const checksum = crc8(commandPacket);
    const finalPacket = Buffer.concat([commandPacket, Buffer.from([checksum])]);

    btSerial.write(finalPacket, function(err, bytesWritten) {
      if (err) console.error(err);
      console.log('Sent command:', finalPacket.toString('hex'));
      btSerial.close();
    });
  });
});

function crc8(data) {
  // ... CRC calculation function as above ...
  let crc = 0;
  for (let i = 0; i < data.length; i++) {
    crc ^= data[i];
    for (let j = 0; j < 8; j++) {
      if (crc & 0x01) {
        crc = (crc >> 1) ^ 0x8C;
      } else {
        crc >>= 1;
      }
    }
  }
  return crc;
}
```

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

### RAML Specific Song Item Definition using Collection-Item

Source: https://raml.org/developers/raml-200-tutorial

Defines a specific song resource using the 'collection-item' resource type. This RAML snippet shows how to apply the reusable type to the '/songs/{songId}' endpoint. It overrides the default GET response to provide a detailed JSON example of a song object, including its ID, title, duration, artist, and album information.

```RAML
/songs:
  ...
  /{songId}:
    type: collection-item
    get:
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "songId": "550e8400-e29b-41d4-a716-446655440000",
                  "songTitle": "Get Lucky",
                  "duration": "6:07",
                  "artist": {
                    "artistId": "110e8300-e32b-41d4-a716-664400445500"
                    "artistName": "Daft Punk",
                    "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
                  },
                  "album": {
                    "albumId": "183100e3-0e2b-4404-a716-66104d440550",
                    "albumName": "Random Access Memories",
                    "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
                  }
```

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

### Generate HTML Documentation from RAML using raml2html

Source: https://raml.org/blog

This snippet shows how to install and use the raml2html command-line interface to generate a single HTML documentation page from a RAML file. It has dependencies on bootstrap and jQuery. The output is an HTML file.

```bash
npm i -g raml2html
raml2html example.raml > example.html
```

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

### RAML Mobile Order API Example

Source: https://raml.org/enterprise/raml-news

This is an example of a RAML 1.0 specification for a Mobile Order API. It defines the API title, base URI, version, and endpoints for managing orders.

```APIDOC
## RAML Mobile Order API

### Description
This RAML specification defines a Mobile Order API with endpoints for listing and creating orders. It includes details on query parameters, request/response bodies, and response types.

### Method
GET

### Endpoint
/orders

### Query Parameters
- **userId** (string) - Required - Use to query all orders of a user

### Method
POST

### Endpoint
/orders

### Description
Creates a new order.

### Method
GET

### Endpoint
/{orderId}

### Description
Retrieves details for a specific order.

### Response
#### Success Response (200)
- **application/json** (assets.Order) - The order details in JSON format.
- **application/xml** (schema: schemas/order.xsd) - The order details in XML format.
```

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

### Define File Uploads with RAML Form Parameters

Source: https://raml.org/developers/raml-200-tutorial

Demonstrates how to define file uploads using 'multipart/form-data' and binary streams in RAML. It shows the structure for specifying file properties within the request body.

```RAML
/file-content:
  description: The file to be reproduced by the client
  get:
    description: Get the file content
    responses:
      200:
        body:
          binary/octet-stream:
            example: !include heybulldog.mp3
  post:
    description: |
      Enters the file content for an existing song entity.

      Use the "binary/octet-stream" content type to specify the content from any consumer (excepting web-browsers).
      Use the "multipart-form/data" content type to upload a file which content will become the file-content
    body:
      binary/octet-stream:
      multipart/form-data:
        properties:
          file:
            description: The file to be uploaded
            required: true
            type: file

```
Tokens:
Raw