webMethods API Gateway tutorial
Author: Chandrasekaran, Vallab (vac@softwareag.com)
Supported Versions: 10.3 and above
Overview of the tutorial
Service registry is a catalog of services, which provides information on live endpoints of services. In micro-service architecture, the same service will be available in multiple locations as micro-services. A service registry stores the information of live endpoints of the services. When a client needs to send a request to a service, the service registry provides the information about the endpoint in which the service is live. API Gateway supports ServiceConsul and Eureka service registries. Both client side discovery and server side discovery of service registries are supported by API Gateway. This tutorial will guide you to configure service registries in API Gateway, to register/deregister API Gateway APIs to/from one or more service registries, and to configure the service registry in routing policy of an API in API Gateway, which enables us to discover an endpoint from service registry during run-time invocation of the API.
Required knowledge
The tutorial assumes that the reader has:
- a basic understanding of API Gateway and its policy enforcement
- a basic knowledge about service registries
- a basic understanding about micro-services architecture to understand why service registry is used in API Gateway context
Why?
Service registry is an essential part of a micro-service based architecture. In micro-service based architecture, there will be multiple micro-service instances for the same API. A micro-service may go down and come up again anytime based on several factors like hardware failure, overload, development activities, etc. A new micro-service instance may be spawned at anytime for various reasons such as - to update recent version of the service, to maintain high availability, etc. Hence It is not possible for a client to get the information about where a particular service might be currently available. Service registry comes into picture to solve the problem in the above scenario.
- When an instance of a micro-service is coming up, the service registry will be notified that this particular service is available in this particular endpoint (only Host-name/IP address and Port). This is called registration.
- Similarly when a micro-service goes down, the service registry is notified about the unavailability of that micro-service instance. This is called deregistration.
- Now, the provider can just share the service registry details and the service name of this API with the client or API Gateway. Now when a client or API Gateway needs to invoke the service, the client/API Gateway just needs to query the service registry with the service name. The service registry returns one of the active endpoint (just the host-name and port) where the service is running. This is called service discovery.
Prerequisite steps
- Install API Gateway 10.3 advanced edition
- Download and run a service registry (Service Consul for this tutorial)
Details
Service registration and discovery overview
Below are the two ways in which interactions occur between the registry and other components.
- Interactions between micro-services and the registry (registration)
- Self-registration
- Third-party registration
- Interactions between clients and the registry (discovery)
- Client-side discovery
- Server-side discovery
Service registration
Most micro-service based architectures are in constant evolution. Services go up and down as development teams split, improve, deprecate and do their work. Whenever a service endpoint changes, the registry needs to know about the change. This is what registration is all about: who publishes or updates the information on how to reach each service.
Self-registration
- When micro-services interact with the registry by themselves, it is self-registration.
- When a service goes up, it notifies the registry.
- When the service goes down, it again notifies the registry about its unavailability.
Third-party registration
- In case of third-party registration, there is a process or service that manages all other services
- This process polls or checks in some way which micro-service instances are running and it automatically updates the service registry
Service discovery
Discovery is the counterpart to registration from the point of view of clients. When a client wants to access a service, it must find out where the service is located (and other relevant information) to perform the request.
Client-side discovery
Client-side discovery forces clients to query a discovery service before performing the actual requests.
Server-side discovery
Server-side discovery makes the API gateway handle the discovery of the right endpoint (or endpoints) for a request. This is normally used in bigger architectures.
Configuring service registries in API Gateway
API Gateway ships two service registry configurations by default - EurekaDefault (a configuration for Eureka Service Registry) and ServiceConsulDefault (a configuration for Service Consul). You can modify these existing service registries and/or add new service registries under "Administration → Service Registries section"
Click on an existing service registry or "Add service registry" button. You will see the following configuration.
|
Field
|
Description
|
|---|---|
|
Field
|
Description
|
| Name |
Name of the service registry instance configured in API Gateway |
| Description | Description of the instance of service registry. |
| Type |
Type of service registry. Available values are: SERVICE_CONSUL and EUREKA. |
| Endpoint configuration | |
| Endpoint URI |
The base URI for the service registry. This should include the IP address or the FQDN (Fully Qualified Domain Name) and the port on which the service registry accepts requests. |
|
Service discovery path |
The relative path of the service registry discovery service. API Gateway appends this path (and the service ID) to the "Endpoint URI" to generate a service discovery request for the service registry. The service registry returns the address (IP address or FQDN) of an application instance for the requested service ID.
|
|
Service registration path |
The relative path of the service registry registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service registration request for the service registry (to register an API Gateway API with the service registry) |
|
Service deregistration path |
The relative path of the service registry de-registration service. API Gateway appends this path (and the service ID) to the Endpoint URI to generate a service deregistration request for the service registry (to deregister an API Gateway API from the service registry) |
|
Connection timeout (seconds) |
Specifies the time (in seconds) after which a connection attempt times out while communicating with the service registry. |
|
Read timeout (seconds) |
Specifies the time (in seconds) after which a socket read attempt times out while communicating with the service registry. |
| SSL configuration | |
| Keystore alias |
List of keystores that are configured in API Gateway. This is used when the service registry is SSL enabled. |
| Key alias |
Lists all the private keys that are present in the selected keystore alias. This is used when the service registry is SSL enabled. |
| Truststore alias |
A truststore contains the certificates that are trusted by API Gateway. If the service registry is SSL enabled its certificate should be added to the selected truststore. |
| Basic authentication details | |
| Username | The basic authentication user name to be used while communication with the registry. |
| Password | The basic authentication password to be used while communication with the registry. |
| Other configuration | |
| Headers |
An HTTP header that is to be included in all the HTTP requests sent to the service registry. |
| Key | Header key for the HTTP header mentioned above. |
| Value | Value for the given HTTP header key. |
For example, a sample configuration for a Service Consul service registry running in localhost will look like below.
Registering API Gateway APIs
Once you have configured your service registry, you can register/deregister API Gateway APIs to/from the service registry. To register an API Gateway API to service registry, follow the below steps. Click on the "APIs" menu in the top menu and go to the "Manage APIs" page. In the list of APIs listed, click on the "Publish" button next to the API you want to register with the service registry.
In the Publish popup that occurs, select "Destination" as "Service registries". The list of service registries configured in the API Gateway are shown. You can choose one or more service registry from the list. Once you have selected a service registry from the list, the list of gateway endpoints of the API are shown under the selected service registry. You can choose one or more gateway endpoints from the list. Only the (host-name and port) details of endpoints chosen are published to the service registry.
In the below example, we have two HTTP ports enabled - "5555" and "5556". So there are two gateway endpoints available for registration but only one of them (5555) is chosen. So only that endpoint of the API (i.e, host-name 'MCVAC02' and port '5555') will be registered to the service registry
Click on "Publish". You will get a success/failure message based on the response from the service registry. If you have selected more than one service registry for publishing, then you will get a publish report containing the success/failure messages as shown below.
Open the Service Consul UI and click on the "Services" menu. You could see that the API "EchoVs_1" is registered to the consul.
Configuring "Service Registry Display Name"
In the above step, you could see that the API is registered to the service registry with name "EchoVS_1". This is nothing but the combination of api name and the api version with underscore in between.
This is the default value of the service name generated by API Gateway when registering to a service registry.
However, you can configure the value of the name to be used when registering to a service registry. This can be done by configuring the "Service registry display name" field under the "Technical Information" section of the API.
For example, edit the EchoVS API and go to "Technical Information" section. In the "Service registry display name" text box, you could see that the default value is populated.
Remove that value and configure the value you would like (eg: myEchoServiceV1). Click 'Save'
Now follow steps 2 to 5 for re-registering the API to the service registry. You could see that the Echo service is registered to the service registry (in our case Service Consul) with the name we configured in above step.
Registering multiple APIs to Service registry
You can also bulk register multiple APIs to one or more service registries from API Gateway UI. Follow the below steps.
Click on the "APIs" menu in the top menu and go to the "Manage APIs" page. Select two or more APIs from the checkbox on the left side of API name as shown below. Click on the "Bulk actions" icon on the right corner of the heading row and click "Publish" as shown below.
In the Publish popup that occurs, select "Destination" as "Service registries". The list of service registries configured in the API Gateway are shown. You can choose one or more service registry from the list. Click Publish.
You will get a publish report containing the success/failure messages for the APIs as shown below.
Deregistering API Gateway APIs
To deregister an API Gateway API from service registry, follow the below steps.
- Click on the "APIs" menu in the top menu and go to the "Manage APIs" page.
- In the list of APIs listed, click on the "Unpublish" button next to the API you want to deregister from one or more service registries.
- In the Unpublish popup that occurs, select "Destination" as "Service registries".
- The list of service registries, to which the API is already published to, are shown. You can choose one or more service registry from the list. If you want to mark the API's metadata in API Gateway as "Unpublished", even in case of failure of deregistration, select the "Force unpublish" checkbox. Click 'Unpublish'.
You will get a success/failure message based on the response from the service registry. If you have selected more than one service registry for unpublishing, then you will get a 'Unpublish report' popup containing the success/failure messages.
Deregistering multiple APIs from Service registry
You can also bulk deregister multiple APIs from one or more service registries from API Gateway UI. Follow the below steps.
Click on the "APIs" menu in the top menu and go to the "Manage APIs" page. Select two or more APIs from the checkbox on the left side of API name as shown below. Click on the "Bulk actions" icon on the right corner of the heading row and click "Unpublish" as shown below.
In the Unpublish popup that occurs, select "Destination" as "Service registries". The list of service registries configured in the API Gateway are shown. You can choose one or more service registry from the list. If you want to mark the API's metadata in API Gateway as "Unpublished", even in case of failure of deregistration, select the "Force unpublish" checkbox. Click Unpublish.
You will get a unpublish report containing the success/failure messages for each of the APIs versus each of the service registry, as shown in the below image.
How lifecycle of API Gateway APIs affect the API registratered in service registry?
On activation/deactivation of API
- An API that is published to a service registry is automatically deregistered from the service registry if the API is deactivated in API Gateway.
- When the API is activated again, it is automatically registered on the same service registry.
On shutdown/restart of API Gateway
- An API that is published to a service registry Is automatically deregistered from the service registry if the API Gateway instance from where it was registered goes down.
- When the API Gateway instance comes up again, the API is registered on the same service registry.
On enable/disable of Ports in API Gateway
- An API endpoint that is published to a service registry is automatically deregistered from the service registry if the port used in the endpoint is disabled in API Gateway.
- When the port is enabled again, it is automatically registered on the same service registry.
Service discovery using API Gateway
Let us see how to discover the endpoints of native services at run-time using API Gateway (This is called Server-side discovery). For the purpose of the demo of this scenario, I have a native REST service which is running in two different ports. I have made a subtle change in the response - when you hit port 1 (9997) you will get the response as below.
On port 2 (9998) you will get the response as below.
I have registered both these endpoints to the service consul as shown below.
You can register an endpoint to service consul by invoking the registration service of service consul. Details of endpoint and payload for service consul registration service are given below.
Endpoint: http://localhost:8500/v1/agent/service/register
Payload:
{
"ID": "MyRESTApi_1", → This is the unique ID for each request. If you want to register two endpoints, make sure this value is unique for both the requests.
"Name": "MyRESTApi", → This is the name of the API registered in Service Consul. API Gateway should discover the service by querying for this name. You should configure this value in the API Gateway routing section.
"Address": "localhost", → This is the host-name of the instance where this instance of native service is running
"Port": 9997 → Port in which this instance of native service is running.
}
Create a REST API from scratch in API Gateway. Configure the technical information to point to one of the API host-name and port (say http://localhost:9997). Configure the Resources and methods section with the corresponding values of native service (in our case, resource path is "/multi" and GET method). Edit the API. Go to the "Policies" tab and select the "Routing" stage. You can configure the service registry discovery in the default configured "Straight Through Routing" policy, or you can configure it in any other routing policies also. All the routing policies support the service registry discovery. We shall see how to configure the service registry discovery in the existing "Straight Through Routing" policy. Same technique applies to all other routing policies also.
Modify the default value configured in the "Endpoint URI" field of "Straight Through Routing" policy. Replace the host-name and port number in the field, with the service registry alias using the below syntax ${REGISTRY_NAME} (For example: ${ServiceConsulDefault}) . In our case, the default value configured in the "Endpoint URI" field of "Straight Through Routing" policy will be http://localhost:9997/${sys:resource_path} and this is replaced as http://${ServiceConsulDefault}/${sys:resource_path}
Go to the "Service Registry Configuration" section and configure the below key-value pair for the Service Discovery Endpoint Parameter → Parameter & Value parameters. "Parameter" should be configured with the path parameter configured in the "Service discovery path" while configuring the service registry. eg: {serviceName}. Note that the flower braces are required. For more information on this, refer the description for "Service discovery path" parameter under the section Configuring service registries in API Gateway. "Value" should be configured with the actual service name which needs to be discovered by the service discovery. API Gateway replaces "Parameter" with "Value" while sending the discover request to service registry.
For example,
- In the example for ServiceConsulDefault service registry shown in "Configuring service registries in API Gateway" section, the value for "Service discovery path" is configured as "/catalog/service/{serviceName}".
- Hence, when this API's routing policy is configured for service registry discovery using ServiceConsulDefault, we should configure the "Service Discovery Endpoint Parameter" with Parameter as "{serviceName}"
- "Value" parameter should be configured as the actual service name to be discovered (in our case this is 'MyRESTApi').
- While sending the discovery request, API Gateway replaces the string "{serviceName}" with "MyRESTApi".
- Hence, in this scenario, the service discovery path will be replaced at runtime as "/catalog/service/MyRESTApi"
Save and activate the API. Invoke the API using the Gateway endpoints. You will get the response from one of the endpoints (say 9998 port).
Now, deregister that endpoint (the port you got in the response in previous step) from Service Consul. Invoke the API Gateway endpoint again. You will get the response from the second endpoint (9997 port or vice versa).
Try deregistering both the endpoints and invoke the API Gateway endpoint. API Gateway will throw 500 Internal Server Error as API Gateway is unable to discover the service from the registry.
Limitations
- Service registry and discovery is supported only for REST and SOAP APIs in API Gateway. It is not supported for Websocket APIs.
References
Please refer the below links for a better understanding on service registries.