Express HATEOAS with YML

This package will generate HATEOAS links automatically based on a configuration file and is based on express-hateoas-links by John Doherty.

Install

Install the package with NPM:

npm install --save express-hateoas-yml

Or with Yarn:

yarn add express-hateoas-yml

Use

Declare and specity the path for the YML/YAML file with the related links:

const hateoas = require('express-hateoas-yml');
const hateoasOptions = {
    linksFile: path.join(__dirname, 'libs/links.yml')
};

In the Examples section you'll find examples of how to configure related links.

Add the middleware to Express:

const express = require('express');
const app = express();

app.use('*', (req, res, next) => hateoas(req, res, next, hateoasOptions));

Examples

Basics

In the following example we've a basic example where the a GET URL /api/v1/customers should return a reference to URL /api/v1/customers/birthdays and method GET.

/api/v1/customers:
  GET:
    - rel: customers
      method: GET
      href: /api/v1/customers/birthtoday

Send your response as usual:

result.data = await controller.getAll();

return res.status(200).json(result);

Then the response body should includes the original resultdata and the links:

{
    "data": [
        {
            "name": "Paulo",
        },
        {
            "name": "Cesar"
        },
        {
            "name": "Silva"
        }
    ],
    "_link": [
        {
            "rel": "customers",
            "method": "GET",
            "href": "http://localhost:3000/api/v1/customers/birthtoday"
        }
    ]
}

Placeholders

The reference can return a link with dynamic URL, like a record id. Note the :1 below:

/api/v1/customers:
  POST:
    - rel: self
      method: GET
      href: /api/v1/customers/:1

Then in the route code:

// save the record as usually
const data = await controller.save(req.body);

// and put the record id as an additional parameters
return res.status(201).json(data, data._id);

URL Parameters

This package will recognize the parameters and replace it before look for links in YML file:

• Object Id will be replaced by :oid
• UUID by :uuid
• E-mail by :email
• Number by :number

Examples:

• /api/v1/customers/123 will be replaced for /api/v1/customers/:number.
• /api/v1/customers/98949bc9-bf0a-4ceb-8f45-fa07ccd39d76 will be replaced for /api/v1/customers/:uuid.

Reuse

It's possible to reuse other definition within the original URL.

/api/v1/customers:
  POST:
    - rel: self
      method: GET
      href: /api/v1/customers/:1
  PUT:
    use: POST

You also can reuse an entire endpoint as shown below where a PUT request will return all related links of GET requests:

/api/v1/customers/:oid:
  PUT:
    use: GET
  GET:
    - rel: sales
      method: GET
      href: /api/v1/customers/:1/sales
    - rel: self
      method: DELETE
      href: /api/v1/customers/:1
    - rel: self
      method: PUT
      href: /api/v1/customers/:1
/api/v1/customers/:email:
  use: /api/v1/customers/:oid
/api/v1/customers/:uuid:
  use: /api/v1/customers/:oid

Property name

By default the related links in the response object will be inside the property named _links as indicative of a metadata. But you can change it's name by setting a propertyName in options object:

const hateoasOptions = {
    linksFile: path.join(__dirname, 'libs/links.yml'),
    propertyName: 'links'
};

Additional data

You can add any extra information within the related link item and it will be included in the response as you can see below:

/api/v1/customers/:oid:
  PUT:
    use: GET
  GET:
    - rel: sales
      method: GET
      description: Get all customer's orders
      href: /api/v1/customers/:1/sales
    - rel: self
      method: DELETE
      warning: Delete this customer permanently
      href: /api/v1/customers/:1
    - rel: self
      method: PUT
      href: /api/v1/customers/:1

Below the result with extra information description and warning

{
    "active": true,
    "_id": "5c1be67e55087519a29065e6",
    "name": "Paulo",
    "_links": [
        {
            "rel": "sales",
            "method": "GET",
            "description": "Get all customer's orders",
            "href": "http://localhost:3000/api/v1/customers/5c1be67e55087519a29065e6/sales"
        },
        {
            "rel": "self",
            "method": "DELETE",
            "warning": "Delete this customer permanently",
            "href": "http://localhost:3000/api/v1/customers/5c1be67e55087519a29065e6"
        },
        {
            "rel": "self",
            "method": "PUT",
            "href": "http://localhost:3000/api/v1/customers/5c1be67e55087519a29065e6"
        }
    ]
}

Bugs

Please use the Project Issues page to report bugs or send suggestions.

License

Licended under ISC License © Paulo César da Silva