The Policy Hub¶
API developers use policies (i.e. interceptors) for performing various types of transformations and validations at the API gateway. However each time a developer is in need of an API Policy, they have to develop the policy from the scratch.
Microgateway policy hub creates a place for developer community to share their extensions with other developers and reuse existing work done by other developers.
How it works¶
As per the below diagram, the developer will utilize the Ballerina Central as the Policy Hub ( i.e. Policy Sharing website) for the purpose of searching, listing and uploading policies (i.e interceptors.). The interceptor functions will be placed inside ballerina modules in the Ballerina Central’s Repository. Users will be able to specify which interceptor to engage per API or per Resource within the OpenAPI Definition. During the build time of a project, the specified module will be pulled from the ballerina central, and the interceptor’s functionality will be applied when the API is being invoked.
Create a new module¶
As discussed earlier Microgateway is using Ballerina Central as the hub for sharing policies. Therefore to share a new policy, it has be ballerina module. Let's look at how to create a new ballerina module which is also a MGW policy.
- Create ballerina interceptor First, you need to have functional and tested interceptor(s) created by following Ballerina Message Transformation guide.
- Setup the ballerina environment This Microgateway version is released with the support for ballerina v1.2.6. Therefore you need to install Ballerina v1.2.6. Go to ballerina downloads and find respective ballerina 1.2.6 distribution for your operating system. Follow Installing Ballerina guide and install ballerina and preferred IDE extension.
Initialize a new Ballerina Project and a Module To create a ballerina module, first we should have a ballerina project. Execute below commands to initialize a new balleina project and a module.
# hello_mgw is the project name. You can give it your own name ballerina new hello_mgw # move inside the new project cd hello_mgw # hello_policy is the module name. This is the name that will be published in the policy hub ballerina add hello_policy
Now the module is ready to add new interceptors. Interceptor source files created in step 1. should be moved into the new ballerina module's source directory.
Build the module
# hello_policy is the module name. ballerina build hello_policy
You can find complete sample project with tests in github.
Share a module in the Hub¶
Follow below steps to share the created module with other Policy Hub users.
Configure Ballerina.toml Ballerina central uses organization name to organize modules by module provider (similar to maven group-id). Therefore before sharing the new module we need to provide the org-name and the version of the module. To increase the discoverability of new module you can define search keywords you'd like to list the module. To do these, Open Ballerina.toml file at the root of the project directory. Then update the org-name and version attributes inside [project] table.
[project] org-name= "org" version= "0.1.0" keywords= ["microgateway", "interceptors"]
Push the module.
ballerina push hello_policy
Using Policy Hub¶
Checkout step by step guide at How to add interceptors from Policy HubTop