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 = ;const hateoasOptions = linksFile: path;
In the Examples section you'll find examples of how to configure related links.
Add the middleware to Express:
const express = ;const app = ; app;
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:
resultdata = await controller; return resstatus200;
Then the response body should includes the original resultdata and the links:
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 usuallyconst data = await controller; // and put the record id as an additional parametersreturn resstatus201;
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 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
Bugs
Please use the Project Issues page to report bugs or send suggestions.
License
Licended under ISC License © Paulo César da Silva