{"id":13526131,"url":"https://github.com/strongloop/microgateway","last_synced_at":"2025-05-15T17:03:01.920Z","repository":{"id":41514136,"uuid":"67075275","full_name":"strongloop/microgateway","owner":"strongloop","description":"IBM API Connect Microgateway framework, built on Node.js \u0026 Nginx","archived":false,"fork":false,"pushed_at":"2019-11-05T04:08:51.000Z","size":4397,"stargazers_count":1195,"open_issues_count":44,"forks_count":182,"subscribers_count":95,"default_branch":"master","last_synced_at":"2025-03-31T16:13:39.036Z","etag":null,"topics":["api-management","apiconnect","gateway","nginx","nodejs"],"latest_commit_sha":null,"homepage":"https://developer.ibm.com/apiconnect","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strongloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-31T21:37:49.000Z","updated_at":"2025-02-27T15:37:34.000Z","dependencies_parsed_at":"2022-09-26T16:21:33.188Z","dependency_job_id":null,"html_url":"https://github.com/strongloop/microgateway","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fmicrogateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fmicrogateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fmicrogateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strongloop%2Fmicrogateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strongloop","download_url":"https://codeload.github.com/strongloop/microgateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694875,"owners_count":20980733,"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-management","apiconnect","gateway","nginx","nodejs"],"created_at":"2024-08-01T06:01:25.589Z","updated_at":"2025-04-07T17:07:13.549Z","avatar_url":"https://github.com/strongloop.png","language":"JavaScript","readme":"# Introduction\n\nThis is fork with datastore cache for http-responses. To enable it you must set env var DATASTORE_USE_LOCAL_CACHE=true.\n\nThe Microgateway is an developer-focused, extensible gateway framework written\nin Node.js for enforcing access to Microservices \u0026 APIs - https://developer.ibm.com/apiconnect/. It supports the\nfollowing core features:\n\n*\tSecure and control access to APIs using Swagger (OpenAPI) Specification\n*\tCollection of pre-built gateway policies for API Key validation, OAuth 2.0,\n    rate limiting, and JavaScript\n*\tCreate gateway policies (security, routing, integration, etc... ) using\n    Swagger extensions (API Assembly)\n*\tSimple interfaces for creating your own gateway policies.\n\nThe role of a Gateway in an API architecture is to protect, enrich and\ncontrol access to API services. These sets of capabilities are often related\nto security and rate limiting, but it also includes the ability to do deeper\nmessage inspection.  For example, you may want to insure that the message\nreceived is properly formed JSON, XML, or data following your own specific\nformat.  In addition, the Gateway can modify the payload or transform it to\nmeet old or new interfaces for the API backend. Finally, the Gateway can\ninvoke multiple services and aggregate responses from multiple API backends.\n\nThe Microgateway is the foundation for all of those things. It is optimized\nto perform security, rate limiting, and much more complex packet processing\nthrough a highly flexible flow-engine.\n\nThe flow-engine is a processing unit that allows you to define a sequence\nof processing policies or tasks that get applied to the transaction as it\npasses through the Gateway for a specific API. These policies may be organized\nin a linear fashion, executing in sequential order. Or, they may have\nconditional logic deciding which set of policies will execute depending on\nvariables that are part of the API flow.\n\nThe Microgateway currently contains the following policies that run implicitly\nbased on swagger definitions:\n\n* **Client_ID/Client_Secret** – Use a client ID and client secret to\n  authenticate and authorize the use of this API\n* **Basic Auth** – Use Basic Auth to authenticate and authorize the use of this\n  API\n* **OAuth 2.0** – Use OAuth2.0 to authenticate and authorize the use of this API\n* **Rate-Limit** – Limit the number of requests per time unit that the\n  subscriber may access this API\n\nThe Microgateway currently contains the following polices that are available\nto the Assembly extension to the swagger definition:\n\n* **if**  - If a condition evaluates to True, execute the corresponding flow.\n* **switch** – Given a set of conditions, execute the flow corresponding to the\n  first condition that evaluates to True.\n* **operation-switch** – Given a set of conditions on the operation, select the\n  first rule where the condition evaluates to True.\n* **throw** – Throw an exception\n* **invoke** – Retrieve a resource using HTTP or HTTPS. Currently supported HTTP\n  request methods or verbs are\n  `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`.\n* **javascript** – Execute a JavaScript program to manipulate or inspect the\n  transaction\n* **set-variable** – Set a variable in the context\n\n# API Designer Toolkit\n\nThe API Designer toolkit provides a graphical interface for the Microgateway.\nYou can download it using NPM via `npm install -g apiconnect`. This toolkit can\nbe also be used for creating enterprise API definitions using IBM API Connect,\nwhich provides features to create and manage APIs on an enterprise scale.\n\nFor more information, see https://developer.ibm.com/apiconnect/.\n\nThe API designer toolkit creates YAML files for the APIs definitions. These can\nthen be tested directly on the internal Microgateway (part of the API Designer\ntoolkit), or you can run them on an external Microgateway by moving the\nunderlying YAML files to the external Microgateway directory.\n\n# The Microgateway Architecture\n\nThe Microgateway was developed with the goal of making something simple,\ncommunity-based, and that could easily be extended for anyone’s needs.\n\nThe Microgateway has the following characteristics:\n\n* Built on Node Express and Loopback frameworks\n* Processes Swagger API definitions via a middleware chain that identifies the\n  API and executes the API definition.\n* Contains a “datastore” that holds the data model of all API artifacts to be\n  processed.\n* Uses a flow-engine to process a variety of policies giving the API designer\n  the ability to perform deep packet processing on the request or response.\n\nA diagram of the Microgateway is shown below. Looking at the diagram, the flow\nof a request is from left to right.  The Microgateway is a collection of\nmiddleware components that process the request in order. Each middleware\ncomponent passes control to the next middleware until the processing of the\nrequest is complete.  The **postflow** and **error-handler** middlewares work\ntogether to return the results back to the client making the request.\n\n![alt text][microgateway-components]\n\n[microgateway-components]: https://github.com/strongloop/microgateway/blob/master/images/readme/MicroGatewayArchitecture2.png \"Microgateway Component Structure\"\n\nThe **urlrewrite** middleware simply modifies the prefix of the URL under\ncertain conditions.  For the most part, this is a passthrough.\n\nThe **context** middleware creates a scratchpad memory area known as the\ncontext. The context is accessible by all middlewares and policies in the flow.\nAny middleware or policy can add, modify or remove variables from the context.\n\nHere are some of the context variables that are automatically populated:\n\n![alt text][context-variables-part1]\n\n[context-variables-part1]: https://github.com/strongloop/microgateway/blob/master/images/readme/ContextVariablesPart1.png \"Microgateway Context Variables\"\n\nOne object that is particularly important is the **message** object. The\n**message** object contains the payload that was received from a request. For\nexample, if you add an **invoke** action, the results from that action will be\nplaced in the **message** object. At the end of the flow, the contents of the\n**message** object will be returned back to the client.\n\nHere are some other context variables:\n\n![alt text][context-variables-part2]\n\n[context-variables-part2]: https://github.com/strongloop/microgateway/blob/master/images/readme/ContextVariablesPart2.png \"Microgateway Context Variables\"\n\nThe **request** object is another important object. It holds all of the\ninformation about the original request that was received by the Microgateway.\nThere are other objects that contain system information, plan information, and\ngeneral API information.\n\nOne important aspect of the context is that it is read-writable by policies and\nmiddleware as they execute. Another important factor is that context variables\ncan be used as substitution parameters inside the conditional policies. This\nallows you to write sophisticated logic flows, simply referencing them through\nconfiguration.\n\nThe **analytics** middleware is used to connect to an external analytics engine.\nIt passes a series of variables from the context in a message to an external\ncollection device.\n\nThe preflow middleware accomplishes the following:\n\n1.\tIdentifies the API (or Swagger definition) to execute.\n2.\tPerforms security associated with that Swagger definition.\n3.\tPerforms rate-limiting for the API.\n4.\tCreates the objects necessary for the assembly (IBM extensions to the\nswagger definition) to be consumed by the flow-engine.\n\nThe flow-engine is a combinational processor that allows you to insert\nsequential logic around a series of policies. The policies can perform any\noperation to the request or response payload. They can be used to retrieve a\nresponse from an API backend or examine the request for security or other needs.\n\nThe flow-engine is built as a vendor extension to the standard Swagger\nspecification. The policies that are referenced in the assembly must have a\npre-built policy. Each one of the policies is a Node.js module that provides the\nprocessing of the message. Each policy also has a policy.yml file that defines\nthe set of properties and behavior of the policy. For examples, visit the\n`policies` directory of the microgateway repository.\n\n\n# Getting Started with the Microgateway\nFollowing are the steps to install and run a stand alone microgateway\n\nStep 1. Clone the microgateway repository\n```\ncd $HOME\ngit clone https://github.com/strongloop/microgateway.git\n```\n\nStep 2. Populate all of the necessary dependencies for the project\n```\ncd $HOME/microgateway\nnpm install\n```\n\nStep 3. Change current working directory to the root directory\n```\ncd $HOME/microgateway/\n```\n\nStep 4. Create a startup script that sets environment variables and starts up\nthe Microgateway. The script file is a simple node.js JavaScript file shown\nbelow. Create this file in the `$HOME/microgateway/` directory.\n\nNote:  The CONFIG_DIR is the folder containing the yaml files holding the API\ndefinitions that you wish to enforce.\n```\n// sample.js\n//\n'use strict';\n\nvar mg = require('./lib/microgw');\nvar fs = require('fs');\n\n// config dir\nprocess.env.CONFIG_DIR = __dirname + '/definitions/myapp';\nprocess.env.NODE_ENV = 'production';\nmg.start(3000);\n```\n\nStep 5. Create a yaml file to define the API. Place the yaml file in the folder\nidentified by the `CONFIG_DIR` environment variable created in the startup script.\nFor this example, we are creating the file sample_1.0.0.yaml in the\n`$HOME/microgateway/definitions/myapp` directory. Note that you can place\nseveral yaml files in this directory and all will be pulled in and used by the\nMicrogateway.\n```\n# sample_1.0.0.yaml\n#\ninfo:\n  version: 1.0.0\n  title: sample\n  description: sample laptop yaml\nbasePath: /sample\nswagger: '2.0'\npaths:\n  /echo:\n    get:\n      responses:\n        '200':\n          description: 200 OK\nx-ibm-configuration:\n  assembly:\n    execute:\n      - javascript:\n          title: write a small json object\n          source: |\n           message.body = { text : 'Hello World' };\nschemes:\n  - http\n```\n\nStep 6. From the root directory, execute the command to start the Microgateway.\n```\ncd $HOME/microgateway/\nnode sample.js\n```\n\nStep 7. Send a curl command to test the API. It should return the\n`{“text”:”Hello World”}` JSON object.\n```\ncurl http://localhost:3000/sample/echo\n```\n\nFor more information on the internal specifics of the Microgateway, you may\nwant to look at the microgateway/test directory. All middleware components\nhave one or more test suites to exercise their interfaces and logic.\n\nFor more examples on how to add various policies to your API assembly, look in\nthe microgateway/test/definitions directory. There are several swagger files\nthat are used to test out the implementation.\n\n# How to contribute to this Project\n\nFor information on contribuging to this project, please look at CONTRIBUTING.md\nand CONDUCT.md as well as the LICENSE.txt file.\n\n\n","funding_links":[],"categories":["API Gateways","JavaScript"],"sub_categories":["Desktop"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fmicrogateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrongloop%2Fmicrogateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrongloop%2Fmicrogateway/lists"}