Governing an existing REST service

This tutorial shows you how to use the service management profile to govern an existing REST service, and control its visibility and use across the organization.

What you should be able to do

At the end of this tutorial, you should be able to:
  • Register an existing REST service and its REST service interface, along with its endpoints, in WSRR.
  • Identify and define the business capability that the service provides.
  • Provide a complete specification of the existing service version, including the service level definition, that can be consumed by other services.
  • Complete the service lifecycle to ensure that the service endpoints are visible and enabled in the various environments.
Note: Before you begin this tutorial, you must complete the steps that are described in Setting up the tutorials, Starting the WSRR dashboard, and Creating an organizational structure.

Introduction

The use of REST for interactions between consumers and providers has become more commonly used. There are many competing specifications available for representing REST in the marketplace. The REST model is not a representation of any single specification; instead, it represents the concepts relevant to governance. WSRR provides guidance about how to govern REST systems and is flexible enough that you can do what you need to do with that representation. This tutorial examines how this is achieved.

REST is represented in the following ways:
  • The description of the interface. The description can be modeled in detail by using the format of one of the REST specifications, or it can be a simple text description contained in a governed document. The WSRR REST model implements a REST service interface.
  • Representation of the endpoint. A REST service, like any other service, has an endpoint with a network address. This endpoint is modeled in the same way as all other endpoints in WSRR so that its state, whether online or offline, can be governed. The REST service can be queried by a runtime system; for example, an enterprise service bus (ESB). The WSRR REST model represents this using a REST service endpoint.
  • Realization of a Capability Version. In the same way that a Capability Version can be realized as a web service or as an SCA Module, it can also be realized by a REST service, which enables a REST service to play a part in the complete governance story.
The SOA governance process can start in either of the following ways:
  • The business plans the services that it needs according to a top-down service lifecycle.
  • The IT department discovers and catalogs the services that it is using, introducing governance and control over existing services.
In this tutorial, we consider the second option: a single REST service for searching a catalog is currently deployed in the production environment, allowing for searching across various categories, such as books. The Catalog Search service is defined by a single YAML file that includes the description of the parameters needed. The path URL defined in the definition file is considered to be relative to where the REST service is deployed; this base addressable location is represented by using a REST service endpoint.
Note: The format of the YAML file is Swagger 2.0; however, any format is acceptable. Many organizations define their REST interactions in basic text documents. The REST Service Interface object is used to represent and reference this definition file as it encodes the format of the interaction with a client of the service.

If you have security enabled, you can add more realism to this tutorial by creating a separate user ID for each role (SOAGovernance, Development, and Operations), and assigning each user ID to its role by using WSRR security. Then, at each stage of the tutorials where you change perspective because the actions are performed by a different role, log out of the WSRR dashboard and log in with the appropriate user ID. You can assign users to roles by using the web UI; for more information, see Add and remove principals for a role.

The tasks that make up this tutorial are divided into a number of sections that form a sequence. If you want to carry out all the tasks, complete the sections strictly in the order shown. However, you can also examine a specific section for reference purposes.

  1. Identifying the business capability provided by a service
    An important part of scoping a service is to identify how it adds value to the business. WSRR uses business capabilities to define the business view of a service.
  2. Defining the REST service interface
    Before the REST service can be defined, the interface on which it is based must be defined.
  3. Defining the REST service
    A new service version called Catalog Search is used to initiate the service lifecycle.
  4. Defining the REST service endpoints
    After the REST service is defined, the next step is to indicate where the service is available by defining REST service endpoints for the different environments.
  5. Completing the service level definition for the service
    After defining and approving a business service, and relating it to a service version, you must complete the service level definition for the service.
  6. Completing the service lifecycle
    After you have described the service in sufficient detail for it to be consumed and programmed against, you must complete the service lifecycle by promoting the service.
Parent topic: Tutorials for the service management profile
Previous topic: Governing an existing service