{"id":26920504,"url":"https://github.com/fgiova/fastify-rest-gateway","last_synced_at":"2026-05-17T00:37:06.537Z","repository":{"id":189709628,"uuid":"515606734","full_name":"fgiova/fastify-rest-gateway","owner":"fgiova","description":"This plugin for fastify 4.x allows you to expose REST APIs for your REST microservices starting from OpenApi contracts hosted into same microservice.","archived":false,"fork":false,"pushed_at":"2023-09-05T14:17:53.000Z","size":261,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-15T16:31:25.446Z","etag":null,"topics":["fastify","fastify-plugin","gateway-api","rest-api"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgiova.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-07-19T13:55:48.000Z","updated_at":"2024-01-15T03:12:00.000Z","dependencies_parsed_at":"2023-08-21T12:44:17.229Z","dependency_job_id":"47669df2-2205-4cd1-ae4f-e512e8da4895","html_url":"https://github.com/fgiova/fastify-rest-gateway","commit_stats":null,"previous_names":["fgiova/fastify-rest-gateway"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fgiova/fastify-rest-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgiova%2Ffastify-rest-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgiova%2Ffastify-rest-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgiova%2Ffastify-rest-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgiova%2Ffastify-rest-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgiova","download_url":"https://codeload.github.com/fgiova/fastify-rest-gateway/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgiova%2Ffastify-rest-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275950661,"owners_count":25558391,"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","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fastify","fastify-plugin","gateway-api","rest-api"],"created_at":"2025-04-01T22:37:26.688Z","updated_at":"2025-09-21T07:05:43.564Z","avatar_url":"https://github.com/fgiova.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fastify rest-gateway\n\n[![NPM version](https://img.shields.io/npm/v/@fgiova/fastify-rest-gateway.svg?style=flat)](https://www.npmjs.com/package/@fgiova/fastify-rest-gateway)\n![CI workflow](https://github.com/fgiova/fastify-rest-gateway/actions/workflows/node.js.yml/badge.svg)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n\n## Description\nThis plugin for fastify 4.x allows you to expose REST APIs for your REST microservices\nstarting from OpenApi contracts hosted into same microservice.\n\nRoutes to be exposed by the gateway must be tagged with the appropriate tags; \nby default \"public-api\" for public APIs, \"private-api\" for hidden APIs.\n\n**Note**\u003cbr\u003e\nTo distribute open-api compliant contracts I recommend using the plugins for fastify [@fastify/swagger](https://github.com/fastify/fastify-swagger) and [@fastify/swagger-ui](https://github.com/fastify/fastify-swagger-ui)\n\n**Warning**\u003cbr\u003e\nThe plugin mandatorily requires the [@fastify/reply-from](https://github.com/fastify/fastify-reply-from) plugin.\n\n## Install\n```bash\nnpm i @fgiova/fastify-rest-gateway @fastify/reply-from\n```\n### Usage\n```js\nconst app = require(\"fastify\")();\nconst replyFrom = require(\"@fastify/reply-from\");\nconst fastifyRestGateway = require(\"@fgiova/fastify-rest-gateway\");\napp.register(replyFrom);\napp.register(fastifyRestGateway, {\n    services: [\n        {\n            host: \"https://petstore.test.com\",\n            openApiUrl: \"/open-api/json\",\n            remoteBaseUrl: \"/v1/test/public-api/\",\n            gwBaseUrl: \"/v1/test/\",\n            \n        }\n    ]\n});\n```\n\nThe plugin can be used in conjunction with [@fastify/swagger](https://github.com/fastify/fastify-swagger) and [@fastify/swagger-ui](https://github.com/fastify/fastify-swagger-ui) to produce an open-api contract of the routes exposed by the fastify-rest-gateway plugin.\n```bash \nnpm i @fgiova/fastify-rest-gateway @fastify/reply-from @fastify/swagger @fastify/swagger-ui\n```\n\n```js\nconst app = require(\"fastify\")();\nconst fastifyRestGateway = require(\"@fgiova/fastify-rest-gateway\");\n\nawait app.register(require(\"@fastify/reply-from\"));\nawait app.register(fastifyRestGateway, {\n    services: [\n        {\n            host: \"https://petstore.test.com\",\n            openApiUrl: \"/open-api/json\",\n            remoteBaseUrl: \"/v1/test/public-api/\",\n            gwBaseUrl: \"/v1/test/\",\n            \n        }\n    ]\n});\n\nawait app.register(require(\"@fastify/swagger\"), {\n    mode: \"dynamic\",\n    openapi: {\n        ...\n    }\n});\nawait app.register(require(\"@fastify/swagge-ui\"), {\n    routePrefix: \"/open-api\",\n});\n```\n\nThe plugin can be used in conjunction with [@fastify/rate-limit](https://github.com/fastify/fastify-rate-limit) to restrict upstream accesses to the target microservice.\n```bash \nnpm i @fgiova/fastify-rest-gateway @fastify/reply-from @fastify/rate-limit\n```\n\n```js\nconst app = require(\"fastify\")();\nconst fastifyRestGateway = require(\"@fgiova/fastify-rest-gateway\");\n\nawait app.register(require(\"@fastify/reply-from\"));\nawait app.register(require(\"@fastify/rate-limit\"));\nawait app.register(fastifyRestGateway, {\n    services: [\n        {\n            host: \"https://petstore.test.com\",\n            openApiUrl: \"/open-api/json\",\n            remoteBaseUrl: \"/v1/test/public-api/\",\n            gwBaseUrl: \"/v1/test/\",\n            hitLimit: {\n                max: (req: FastifyRequest) =\u003e {\n                    return 10;\n                },\n                keyGenerator: (req: FastifyRequest) =\u003e {\n                    return `${req.ip}_test`;\n                },\n                timeWindow: 5000\n            }\n        }\n    ]\n});\n\nawait app.register(require(\"@fastify/swagger\"), {\n    mode: \"dynamic\",\n    openapi: {\n        ...\n    }\n});\nawait app.register(require(\"@fastify/swagge-ui\"), {\n    routePrefix: \"/open-api\",\n});\n```\n\nThis plugin can be used in conjunction with [@fastify/restartable](https://github.com/fastify/restartable) to reload the routes when open-api contracts of microservices are changed.\n```bash \nnpm i @fgiova/fastify-rest-gateway @fastify/reply-from @fastify/rate-limit @fastify/restartable\n```\n\n```js\nconst app = require(\"fastify\")();\nconst fastifyRestGateway = require(\"@fgiova/fastify-rest-gateway\");\nconst restartable = require(\"@fastify/restartable\");\n\n\nasync function createApp (fastify, opts) {\n    const app = fastify(opts)\n\n    await app.register(require(\"@fastify/reply-from\"));\n    await app.register(require(\"@fastify/rate-limit\"));\n    await app.register(fastifyRestGateway, {\n        services: [\n            {\n                host: \"https://petstore.test.com\",\n                openApiUrl: \"/open-api/json\",\n                remoteBaseUrl: \"/v1/test/public-api/\",\n                gwBaseUrl: \"/v1/test/\",\n                refreshTimeout: 60000, // each 60s reload open-api contract from host if are changed, restart fastify\n                hitLimit: {\n                    max: (req: FastifyRequest) =\u003e {\n                        return 10;\n                    },\n                    keyGenerator: (req: FastifyRequest) =\u003e {\n                        return `${req.ip}_test`;\n                    },\n                    timeWindow: 5000\n                }\n            }\n        ]\n    });\n\n    await app.register(require(\"@fastify/swagger\"), {\n        mode: \"dynamic\",\n        openapi: {\n            ...\n        }\n    });\n    await app.register(require(\"@fastify/swagge-ui\"), {\n        routePrefix: \"/open-api\",\n    });\n\n    return app;\n}\n\nconst app = await restartable(createApp, { logger: true });\nconst host = await app.listen({ port: 3000 });\n\n```\n\n\n### Options\n| Option                   | Type           | Description                                                                                                 |\n|--------------------------|----------------|-------------------------------------------------------------------------------------------------------------|\n| services                 | array          | The list of services to expose.                                                                             |\n| services[].host          | string         | The host of the service.                                                                                    |\n| services[].openApiUrl    | string         | The URL of the OpenApi JSON contract (default: /open-api/json).                                             |\n| services[].remoteBaseUrl | string         | The baseUrl of the remote service.                                                                          |\n| services[].gwBaseUrl     | string         | The baseUrl where the service will be connected on the gateway                                              |\n| services[].tag           | string         | Optional tag for selecting target routes to expose (default: public-api)                                    |\n| services[].hiddenTag     | string         | Optional tag for selecting target routes to expose, but hidden on fastify-swagger (default: private-api)    |\n| services[].preHandler    | FastifyHandler | Optional Fastify Pre Handler function to add to each service route                                          |\n| services[].hooks         | object         | Optional hooks for each route exposed                                                                       |\n| services[].hitLimit      | object         | Optional limit configuration for each route exposed                                                         |\n| defaultLimit             | object         | Optional default limit configuration                                                                        |\n| gwTag                    | string         | Optional default tag for select target routes to expose (default: public-api)                               |\n| gwHiddenTag              | string         | Optional default tag for select target routes to expose, but hidden on fastify-swagger  (default: X-HIDDEN) |\n| ignoreHidden             | boolean        | Optional flag to ignore hidden routes                                                                       |\n| refreshTimeout           | number         | Optional interval in ms for watching open-api contracts and reload through Fastify restartable              |\n\n### Service Hooks\n| Option                      | Type           | Description                                                                  |\n|-----------------------------|----------------|------------------------------------------------------------------------------|\n| onRequest                   | FastifyHandler | Optional Fastify OnRoute Handler function to add to each service route       |\n| onResponse                  | FastifyHandler | Optional Fastify OnResponse Handler function to add to each service route    |\n| onError                     | FastifyHandler | Optional Fastify OnError Handler function to add to each service route       |\n\n### Service limit options\n| Option       | Type               | Description                                                                                              |\n|--------------|--------------------|----------------------------------------------------------------------------------------------------------|\n| max          | number \\| function | Optional sync/async Function or number maximum hit per timeWindow (default: 1000)                        |\n| keyGenerator | function           | Optional sync/async function to generate a unique identifier for each incoming request (default: req.ip) |\n| timeWindow   | number             | Optional the duration of the time window in ms (default: 60000)                                          |\n\n\n## License\nLicensed under [MIT](./LICENSE).\n\n### Acknowledgements\nThis project is kindly sponsored by: isendu Srl [www.isendu.com](https://www.isendu.com)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgiova%2Ffastify-rest-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgiova%2Ffastify-rest-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgiova%2Ffastify-rest-gateway/lists"}