Endpoint Management

In an SOA environment, tracking and management of service endpoints is a key task. Not only is your SOA environment likely to have many individual services, but many of those services are deployed on multiple endpoints.

It acquires additional endpoints as it moves through its lifecycle. For example, by the time a service goes into production, it is usually available at three different endpoints in your environment: at development endpoint, test endpoint, and production endpoint. To track the endpoints that a service acquires as it moves through its development cycle, add the endpoints to the metadata for the service in the registry.

It has different endpoints to accommodate the needs of different consumer applications. For example, you may offer the same service over multiple entry protocols (for example, both JMS and HTTP) and with different security mechanisms. In CentraSite, you accommodate these needs by exposing the service over multiple virtual services.

When a consumer application is written to use static binding, the program binds to a specified address at run time (that is, an endpoint that is already known by the program). When a developer creates a program that uses static binding, he or she gets the endpoint of the service from CentraSite at design time. Typically, this end point is added to a configuration file or a parameter setting that the consumer program reads at run time. If the actual endpoint of the service is modified, the consumer program must be configured to access the service at its new endpoint.

When a consumer application is written to use dynamic binding, the program looks up the service's address at run time and binds to that address. To use this type of binding, a developer must write a query to retrieve the service's endpoint from CentraSite. At run time, the consumer program executes the query and binds to the endpoint that the query returns. If the endpoint of the service changes, one only has to update the service's endpoint information in CentraSite. Nothing has to be changed in the consumer application.

Within CentraSite Business UI, the endpoints for a service are shown in the Provider Overview profile on the Service Details page. In this panel, an endpoint is represented as a specific Access URI (that is, address where the service is deployed).

When a native service moves through its lifecycle, it usually gains additional endpoints. For example, during development, a developer generally deploys the service somewhere in the development environment. When the service moves to the testing phase, it is generally deployed at another endpoint for testing. Finally, when the service is placed in production, the operations organization deploys the service at an endpoint in the production environment.

Each time you deploy a native service to an additional endpoint, you must add the new endpoint to the service in CentraSite. To do this you:

When you attach the updated WSDL to the service, CentraSite automatically updates the binding information on the service's Operations panel.

Note:
Although it is possible to represent the development, test, and production endpoints as individual services in the registry, Software AG recommends that you avoid doing this. Such an approach produces a large amount of duplicated metadata and does not return any real benefits. Instead, maintain just one catalog entry for a native service and add the service endpoints to this entry as the service progresses through its lifecycle.

If you are using a single-stage deployment of CentraSite, services remain in the same registry for their entire lifecycle. Therefore, in this type of registry, the catalog entry for a service includes the service's development, test, and production endpoints.

The following shows an example of a service that has endpoints in the development, test, and production environments. Note that the naming scheme that has been used to identify the bindings for this service clearly indicates the environment in which the endpoint resides. In a single-stage environment, the development, test, and production endpoints are listed for the service as described in the following image:

Important:
The endpoints for a service are visible to any user who has View permission on the service in CentraSite. To prevent unauthorized access to the services themselves, ensure that appropriate security measures are in place at these endpoints.

In a multi-stage deployment, the set of endpoints that you publish to the registry varies according to needs of the registry's audience. In a two-stage deployment, for example, you would list the service's development and test endpoints on the creation CentraSite and you would list the service's test and production endpoints on the consumption CentraSite.

Example of the bindings you would see if you were to view a service in the creation CentraSite and in the consumption CentraSite.

When a service has multiple endpoints, the binding names give users a hint as to the endpoint's function. As a best practice, consider adopting a naming convention for bindings that identifies service endpoints in a clear and consistent manner. (This practice is especially important if your consumer applications queries the registry to obtain a service endpoint run time). Each binding name includes a suffix to indicate the environment in which the endpoint resides.

Binding names are derived from the port names in the service WSDL, hence, to produce bindings whose names conform to the particular naming scheme that you have adopted, you must assign the appropriate names to port definitions in the WSDL.

For example, to produce the binding names shown in the single-stage example described in Bindings for a Service in a Single-Stage Registry, the port definitions in the WSDL must look as follows. Naming conventions for bindings must be applied to the port names in the WSDL:

When you create a virtual service, CentraSite generates a WSDL file for the virtual service. Initially, API Gateway generates this WSDL file as an abstract WSDL file, and is represented as an empty WSDL in the <protocol>:// format. However, when you deploy the virtual service, CentraSite replaces the port definitions in this WSDL file with a port definition that specifies the virtual service's endpoint on the API Gateway. At this time, it also updates the binding information that appears on the virtual service's Operations panel.

CentraSite automatically updates the port definitions in the virtual service WSDL and regenerates the corresponding bindings any time you deploy, undeploy, or redeploy the virtual service.

As the endpoint information for virtual services is generated and updated by CentraSite, you must not manually edit the endpoint information for virtual services. In other words, unlike native services, you must not manually add endpoints to the WSDL of a virtual service. Instead, simply allow CentraSite to generate and manage the endpoints for the virtual services that you deploy.

In the consumption CentraSite, the catalog entry for a native service provides consumers with bindings to the test instance of the service and to the production instance of the service. However, with a virtual service, you cannot do this. The set of bindings for a virtual service are generated and managed automatically by CentraSite, and you cannot manually add bindings to this set.

If you have a test instance of a virtual service deployed on the API Gateway in your test environment, and you would like to disclose that endpoint to users when they view the virtual service in the registry, you can identify the endpoint in a separate attribute (that is, as additional metadata) within the virtual service on the consumption CentraSite.

Note:
If you have consumer applications that dynamically bind to a virtual service, be aware that those applications have to bind against the creation CentraSite during the testing phase of their development and against the consumption CentraSite when they enter the production phase.

Often you may want to deploy a service on multiple endpoints to make the service available over multiple transports and security mechanisms. For example, you may want to extend the same service over JMS and HTTP transports or you may want to allow internal users to access a service using basic HTTP user name or password credentials and you may require other users to submit digital certificates.

To accommodate these kinds of operational requirements for a native service, you deploy multiple virtual services for a single native service. For example, to make a particular native service available to consumers over both HTTP and JMS, you would create two virtual services for the native service: one that accepts requests over HTTP and another that accepts requests over JMS. Both virtual services would route requests to the same native service at the back end.

The following shows a registry in which a native service (SalesReportingService) has been exposed over two virtual services. Virtual Services provide two transports for one native service:

Note:
To make it easier to manage virtual services, consider adopting a naming convention like the one shown in this section. Doing so makes it easier to identify virtual services and the native service with which they are associated. The names of virtual services cannot contain spaces or special characters (except _ and -). Consequently, if you adopt a convention that involves using the name of the native service as part of the virtual service name, then the names of the native services themselves must not contain characters that are invalid in virtual service names.

When you create a virtual service, CentraSite establishes a relationship between the virtual service and the native service from which you created it. If you create multiple virtual services for a native service, each of the virtual services has an established relationship to the native service.

The relationships that CentraSite creates between a native service and a virtual service enables you to use the Asset Navigator feature to easily navigate and visualize a native service and quickly locate all of its virtual services. Example of the Asset Navigator tool lists the virtual services associated with a native service.

Important:
To ensure that a relationship is established between a native service and virtual service, always use the Search for Endpoint button to set the Route To address in a virtual service's Routing Protocols processing step. Do not manually type this address into the Route To field. If you type the address manually, the relationship to the appropriate native service is not be created.