Governing an existing REST service

This tutorial shows you how to use the governance enablement 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:
Note: Before you begin this tutorial, you must complete the steps that are described in Setting up the tutorials 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 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: 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 XML file that includes the description of the parameters needed. No deployment information in available in this definition file because the 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 this file is not one of the existing specifications and is given only for illustrative purposes. 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 (Business, 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 web UI 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 Service is used to initiate the service lifecycle.
  4. Defining the REST Service Endpoints
    When the REST service has been defined, the next step is to indicate where the service is available by defining REST service endpoints for the different environments.
  5. Providing scoping and planning information for the service
    After defining and approving a business service, and relating it to a service version, you must identify other planning and governance information for the service version.
  6. Providing a service level definition for the service
    After completing the scoping and planning information you must provide a clear statement about the service levels that consumers of this service can access.
  7. Completing the service lifecycle
    After you have described the service in sufficient detail for it to be consumed and programmed against and have deployed an implementation of the service, you must declare the endpoints in the registry so that it is promoted to, and therefore visible in, the appropriate environments.
Parent topic: Tutorials for the governance enablement profile
Previous topic: Governing an SCA service: the consumer story
Next topic: Customizing runtime environments