{"id":19528498,"url":"https://github.com/orca-scan/express-hateoas-links","last_synced_at":"2026-05-29T07:06:02.883Z","repository":{"id":118403252,"uuid":"59766155","full_name":"orca-scan/express-hateoas-links","owner":"orca-scan","description":"Extends express res.json to simplify building HATEOAS enabled REST API's","archived":false,"fork":false,"pushed_at":"2023-01-23T17:58:57.000Z","size":78,"stargazers_count":32,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-11T06:46:26.195Z","etag":null,"topics":["api","express","hateoas","nodejs","rest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orca-scan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-26T16:30:09.000Z","updated_at":"2025-01-06T17:03:13.000Z","dependencies_parsed_at":"2023-05-01T08:32:02.981Z","dependency_job_id":null,"html_url":"https://github.com/orca-scan/express-hateoas-links","commit_stats":{"total_commits":32,"total_committers":3,"mean_commits":"10.666666666666666","dds":0.5,"last_synced_commit":"ea45c2e7a69d2222a7b31c94a7651d7e54859cd0"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/orca-scan/express-hateoas-links","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Fexpress-hateoas-links","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Fexpress-hateoas-links/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Fexpress-hateoas-links/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Fexpress-hateoas-links/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orca-scan","download_url":"https://codeload.github.com/orca-scan/express-hateoas-links/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Fexpress-hateoas-links/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265456048,"owners_count":23768677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","express","hateoas","nodejs","rest"],"created_at":"2024-11-11T01:18:58.892Z","updated_at":"2026-05-29T07:06:02.876Z","avatar_url":"https://github.com/orca-scan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-hateoas-links\n\n[![Tests](https://img.shields.io/github/actions/workflow/status/orca-scan/express-hateoas-links/ci.yml?label=Tests)](https://github.com/orca-scan/express-hateoas-links/actions/workflows/ci.yml)\n[![Downloads](https://img.shields.io/npm/dm/express-hateoas-links.svg?label=Downloads)](https://www.npmjs.com/package/express-hateoas-links)\n\nExtends express `res.json` to simplify building HATEOAS enabled REST API's by appending links to JSON responses.\n\n## Installation\n\n```bash\nnpm install --save express-hateoas-links\n```\n\n## Usage\n\n```js\n// send person object with HATEOAS links added\nres.json(personObject, [\n    { rel: \"self\", method: \"GET\", href: 'http://127.0.0.1' },\n    { rel: \"create\", method: \"POST\", title: 'Create Person', href: 'http://127.0.0.1/person' }\n]);\n```\n\nOptionally exclude/remove links based on rel value:\n\n```js\nres.json(personObject, [\n    { rel: \"self\", method: \"GET\", href: 'http://127.0.0.1' },\n    { rel: \"create\", method: \"POST\", title: 'Create Person', href: 'http://127.0.0.1/person' }\n], [ 'create' ]); // \u003c- removes `create` link\n```\n\n## Typical use case\n\nThe example below adds a self \u0026 create link to a JSON schema used to create a person. This allows the consuming application to understand what properties are required to create a Person and the destination URL to post to, removing the need for the application to hard code API links. \n\n```js\nvar express = require('express');\nvar app = express();\nvar hateoasLinker = require('express-hateoas-links');\n\n// replace standard express res.json with the new version\napp.use(hateoasLinker);\n\n// standard express route\napp.get('/', function(req, res){\n\n    // create an example JSON Schema\n    var personSchema = {\n        \"name\": \"Person\",\n        \"description\": \"This JSON Schema defines the parameters required to create a Person object\",\n        \"properties\": {\n            \"name\": {\n                \"title\": \"Name\",\n                \"description\": \"Please enter your full name\",\n                \"type\": \"string\",\n                \"maxLength\": 30,\n                \"minLength\": 1,\n                \"required\": true\n            },\n            \"jobTitle\": {\n                \"title\": \"Job Title\",\n                \"type\": \"string\"\n            },\n            \"telephone\": {\n                \"title\": \"Telephone Number\",\n                \"description\": \"Please enter telephone number including country code\",\n                \"type\": \"string\",\n                \"required\": true\n            }\n        }\n    };\n\n    // call res.json as normal but pass second param as array of links\n    res.json(personSchema, [\n        { rel: \"self\", method: \"GET\", href: 'http://127.0.0.1' },\n        { rel: \"create\", method: \"POST\", title: 'Create Person', href: 'http://127.0.0.1/person' }\n    ]);\n});\n\n// express route to process the person creation\napp.post('/person', function(req, res){\n    // do some stuff with the person data\n});\n```\n\nYou can set `req.disableHATEOAS = false` within a controller or pass `?hateoas=false` to disable HATEOAS links.\n\n### Output\n\n```json\n{\n    \"name\": \"Person\",\n    \"description\": \"This JSON Schema defines the parameters required to create a Person object\",\n    \"properties\": {\n        \"name\": {\n            \"title\": \"Name\",\n            \"description\": \"Please enter your full name\",\n            \"type\": \"string\",\n            \"maxLength\": 30,\n            \"minLength\": 1,\n            \"required\": true\n        },\n        \"jobTitle\": {\n            \"title\": \"Job Title\",\n            \"type\": \"string\"\n        },\n        \"telephone\": {\n            \"title\": \"Telephone Number\",\n            \"description\": \"Please enter telephone number including country code\",\n            \"type\": \"string\",\n            \"required\": true\n        }\n    },\n    \"links\":[\n        {\n            \"rel\": \"self\",\n            \"method\": \"GET\",\n            \"href\": \"http://127.0.0.1\"\n        },\n        {\n            \"rel\": \"create\",\n            \"method\": \"POST\",\n            \"title\": \"Create Person\",\n            \"href\": \"http://127.0.0.1/person\"\n        }\n    ]\n}\n```\n\n## Contributing\n\n1. Fork it!\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -m 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request\n\n## Tests\n\nYou can run the unit tests by changing directory into the express-hateoas-links director within your node_modules folder, and run the following commands:\n\n```bash\nnpm install   // install modules dev dependencies\nnpm test      // run unit tests\n```\n\n## Star the repo\n\nPlease star the repo if you find this useful as it helps us priorities which open source issues to tackle first.\n\n## History\n\nFor change-log, check [releases](https://github.com/orca-scan/express-hateoas-links/releases).\n\n## License\n\nLicensed under [MIT License](LICENSE) \u0026copy; Orca Scan, the [Barcode Scanner app](https://orcascan.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forca-scan%2Fexpress-hateoas-links","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forca-scan%2Fexpress-hateoas-links","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forca-scan%2Fexpress-hateoas-links/lists"}