The user who registers a service in Anypoint™ Service Registry via the registry web application or the API becomes its service owner. After registration, you can add additional service owners, so that a single service can have multiple owners. A service owner (and all users with administrative accounts, also known as organization owners) can view service information and perform maintenance and management tasks that are not accessible by other users. For a full description of role-specific privileges, see Account Types and User Roles.
A service owner registers, maintains, and manages the lifecycle of a service. The owner conducts all service maintenance and lifecycle management operations from the service's main screen, which offers a user-friendly cloud-based portal where you can manage service details. A service owner can manage metadata, endpoints, runtime policies, SLA tiers, and – as the service is updated and changed over time – can add, update, or deprecate various service versions.
Advantages of Using the Service Repository
Having all developers register their consumer and provider applications in the Service Registry's cloud-based repository confers a number of benefits to the organization as a whole by facilitating effective SOA governance. As a service owner, registering your service also confers direct benefits to you.
- You can be confident that your service is published to a centrally accessible platform securely hosted in the cloud.
- You have insight into what consumers are accessing your service.
- You have clear lines of communication with consumers, facilitating transparent version control.
- You can specify and enforce contract management based on your customized SLA tiers.
- You are able to add and remove policies at runtime.
- You can store artifacts related to your service in central storage repository.
This document covers how to register and manage a service using the Anypoint Service Registry web application. Note, however, that you can also perform all of the same operations via the Anypoint Service Registry REST API.
Registering a Service
Complete the following procedure to register a new service in Anypoint Service Registry.
- Click the Services icon in the top navigation bar, then click Add Service.
Anypoint Service Registry opens a three-step Add Service wizard. In the Service Details step, fill in the required details according to the table below, then click Next Step.
Field Best Practices Name Enter a name with only upper and lowercase letters, numbers, spaces, and dashes. No other special characters. Summary Enter a brief, descriptive summary that tells users what your service does. This summary appears immediately under your service name in the service catalog. You can edit this text at any time. Description Enter a longer description here. This description is visible to users who click through to your service's main screen in the registry. You can edit this text later and update it as your service evolves. However, note that individual versions of your service also have a release notes field for specific updates relevant only to new versions.
In the Version Details step, fill in the required details according to the table below, then click Next Step.
Field Best Practices Major Major component of the version number. Must be an integer. Minor Minor component of the version number. Must be an integer. Revision Revision component of the version. This field accepts any string. Release Notes Optional. Note that if you wish to format your release notes, you can wait until you have finished registering your service, then edit the release notes from the service's main screen in a Markdown-enabled editor using the Showdown script library.
- In the Version Endpoints step, click Add Endpoint. (Note that this step is not required. If you prefer to skip this step and add your endpoints later, click Finish.)
In the Create Endpoint dialog, fill in the required details according to the table below, then click Add Endpoint. (You can edit any of these fields later using the Edit button next to the endpoint on the service's main screen, with the exception of the endpoint URL. If you need to alter the URL, delete the endpoint and enter a new one.)
Field Required Best Practices URL Yes
Specify the full address of the inbound endpoint to which consumer service calls should be directed. The following endpoint types are supported for all service registry features:
You can specify any valid internet protocol, but note that other protocols have not been validated to work with all service registry features.
Status Yes This status appears next to your endpoint URL to all users who view your service's main screen. Select Active if this endpoint is currently supported for service calls. Select Inactive if this endpoint is deprecated or otherwise out of service. Environment Yes The environment appears next to your endpoint status to all users who view your service's main screen. (This drop-down menu is populated by the environment options specified in the settings accessible via the Administration menu, available only to organization owners.) Metadata Key and Value No You can append multiple metadata key/value pairs to your endpoint. You must define each key's corresponding value and commit each key using the Append Metadata button before defining the next metadata tag. Metadata that you define here can be used by consumers to dynamically resolve endpoint(s) in their service calls.
- Repeat steps 4 and 5 to define any additional endpoints for your service. When done, click Finish. Your service is now registered in the repository.
Managing Service Details
From your service's main screen, you can manage all the details of your service. Think of your service's main screen as your command and control center over your service's registry profile in the cloud. From this page, you can:
- edit the information that you already entered when initially registering the service
- configure additional information such as metadata tags, taxonomies, SLA tiers, policies, and technical and business contacts
- create new versions of your service, delete or change the status of service versions, or delete the service entirely
This section illustrates an example of a service's main screen from the service owner or administrator perspective. Click the image below to enlarge it.
Your service name, summary, and description. All of this information is consistent across all versions of your service, thus you do not need to re-enter or configure any of this information when you create a new version of your service. Click the pencil icon next to any item to edit the information.
Note that Anypoint Service Registry computes a serviceId using the service name you entered when you registered the service, with spaces replaced by dashes. This formatted version of the name – also viewable by hovering your mouse over the service's name – is what should be used in service calls directed to the registry. This serviceId does not change after it is initially created, even if you edit the name of the service.
|2||Release notes||Version||Click anywhere in this area to access the release notes for the selected version, then click the pencil icon to open the Markdown-enabled editor. Use the Showdown script library to format your release notes.|
|3||Ratings and Reviews||Version||Click anywhere in this area to expand the section. All registry users can rate and leave reviews of your service here. The average rating of your service is shown under the version number in the version information pane (see 7, below).|
|4||Tags and Taxonomies||Service||Any tags and taxonomies that you have applied to the service appear in this area of the screen. All of this information is consistent across all versions of your service, thus you do not need to re-enter or configure any of this information when you create a new version of your service. Click the + icon next to tags or taxonomies to add new ones. Tags and taxonomies are both searchable via the search tool at the top of the registry web application. Read more about applying tags and taxonomies.|
|5||Version information tabs||Version||Note the series of tabs along the bottom of your screen: Endpoints, Consumers, SLA Tiers, and Artifacts. These tabs and all of the information they contain are specific to the service version you are currently viewing. When you create a new version of a service, the data in these tabs does not carry over into the new version. Read more about managing endpoints, defining SLA tiers, and adding artifacts.|
|6||Service menu||Service||The icon of three horizontal lines in the upper right corner of the service profile leads to your service menu. Click this menu icon if you want to take steps to delete your service.|
|7||Version menu||Version||The icon of three horizontal lines in the upper right corner of your screen leads to your version menu. From this menu, you can create a new version, delete the current version, or toggle the current version's status to either Active or Inactive. You can also apply runtime policies to your service version from this menu.|
|8||Version information pane||Version|
This area summarizes key information about the version currently selected. The version number and status (active/inactive) indicates which version you are currently viewing. Click the arrows next to the status to navigate to other versions, if other versions exist.
The registry calculates an average rating for the selected service version based on all ratings left in the Ratings and Reviews section (see 3, above) and displays it immediately underneath the service version number.
The Request Contract button also appears in this pane. The button is green when contract requests are possible, and gray when they are not. Contract requests are only possible for service versions which are marked as Active. Read more about contract management.
The Analytics button leads to the Analytics screen, where you can view helpful service consumption data about your service version. Read more about service analytics.
This pane displays the number of consumers who have contracts with this service version, as well as the number of active endpoints. It also displays any runtime policy characteristics, signaling which policies are applied to a service version or specific endpoints. For more about characteristics, see runtime policy management.
|9||Service information pane||Service||The service owners, technical contacts, business contacts, and basic creation and modification data appear in this area. This information is consistent across all versions of your service, thus you do not need to re-enter or configure any of this information when you create a new version of your service. Click the pencil icons next to each title to add additional contacts.|
The screenshot below is an example of the same screen from the perspective of a user who is neither the service owner nor an administrator. Note that the service menu, version menu, and edit icons are all missing in this view. On the version information tabs, users can view – but not edit – the content.
Applying Tags and Taxonomies
Apply tags and taxonomies to your service by clicking the + icons. Tags and taxonomies are both searchable via the search tool at the top of the registry web application.
Tags are open-ended: you can tag your service with any metadata that you like. Service Registry converts your tags to all uppercase letters. Spaces, numbers, and special characters are all permitted, except for double-quotes (").
Taxonomies are not open-ended. All users are limited to the same set of taxonomies defined by organization owners. Click the + icon and start typing to display tag suggestions. Read more about how organization owners define and manage taxonomies.
Click the Endpoints tab to view a list of all the endpoints you have defined for this service version. You can add or edit your endpoints from this tab.
Each endpoint is preceded by an icon, either a gray eye or a blue eye, visible only to service owners and administrators.
- A gray eye indicates the agent is not currently tracking the endpoint – either Mule is not running, the Mule application supporting this endpoint is not deployed, or the agent is down.
- A blue eye indicates that the agent is currently tracking the endpoint, which means that the registry is successfully communicating with the underlying Mule application via the agent.
Click the edit icon to view or adjust the details of each endpoint, including the metadata. Metadata is required to make it possible for consumers to resolve endpoints dynamically based on specific business logic, so enter metadata keys and values with this in mind. For example, if you want to make it possible for consumer service calls to your service to resolve different endpoints based on the region in which consumer application is hosted, you might add metadata as follows:
|Endpoint||Metadata Key||Metadata Value|
Or, if you want to route consumers to different endpoints based on their business unit, you might add metadata as follows:
|Endpoint||Metadata Key||Metadata Value|
Other users who view your service endpoints can click an icon next to each endpoint to view the metadata defined for that endpoint. They can then format their service calls to query the registry for appropriate endpoints based on that metadata. Read more about the advantages of service virtualization.
Managing SLAs and Contracts
Click the SLA Tiers tab to view, edit, and add SLA tiers for this service version. Other users who view your service see exactly what you see on this tab, with the exception of the edit and delete icons. Read more about defining SLA tiers.
Click the Consumers tab to view a list of all active contracts for this service version. (Note that all other users who are not the service owner or an administrator are not able to see the contract keys on this tab.) You can revoke a contract by clicking the trash can icon next to it. This tab offers a quick way to see who you need to contact if you are planning upgrades to your service and want to migrate your users to a new version. Read more about service lifecycle management.
Click the Artifacts tab to view and upload files that you want to attach to the service version. You can upload documentation, WSDL, XSD schemas or any other kinds of files associated with your service version. Other users can view and download files, but only service owners and administrators can delete them.
To upload files, you can click anywhere within the Attach Artifact zone, or you can drag and drop a file or multiple files into that zone. The maximum file size is 20MB. Most common file types are permitted.
Managing Runtime Policies
You can manage runtime policies for your service either at the service version level or at the endpoint level. Service Registry enforces policies from the top down. Any policies applied at the service version level automatically apply to all endpoints in that service version. For a step-by-step guide on how to create and apply policies to your service version or endpoints, refer to Runtime Policy Management.
Viewing Service Analytics
You can view analytics information about your service version by clicking the blue Analytics button. You can monitor service requests, errors, and top consumers. Read more about service analytics.
Service Lifecycle Management
Change is inevitable, and your services are no exception. Managing the lifecycle of your service within Anypoint Service Registry is a transparent and orderly process. For example, you don't have to create a new service if you change the data model in your Mule application; instead, create a new version of your service. Creating a new version of the same service allows you to capture information that remains relevant, so that you don't have to start from scratch. Most importantly, other users in your organization can follow a clear path of transition to your new version while still having access to all the information of the older versions.
To create a new version, click on the version menu (the three horizontal lines in the upper right corner of the screen), then click Create new version. The Service Registry asks you for a new version number, optional release notes, and endpoints, as with the first three steps of the process to register a new service. In the new version, note that your service profile information, tags and taxonomies, and service information pane have all stayed the same. You can configure all the version-specific information to reflect whatever changes are relevant for this new version.
If consumers are actively using your previous version, you may wish to migrate them to your new version. You can quickly access the list of contracted consumers by going to that version's Consumers tab. Click each consumer to see the consumer owner and other contacts and communicate with them about your new version. To ensure their service is not interrupted, consumer owners must create new contracts for the new version of the service before revoking old contracts. The new contract key and/or version number will also need to be adjusted in any service calls directed at your new version. See the developer guide for more information about formatting service calls.
While you are transitioning consumers over to an updated version of your service, you may want to prevent consumers from creating new contracts for your old service version. Mark your older service version as Inactive via the version menu. When your service version is marked inactive, no new contracts will be permitted. However, existing contracts will continue to function.
Once you have transitioned all consumers onto newer versions of your service, you may wish to permanently delete the deprecated version from the registry. You can delete the service version from the service version menu.
Delete service versions with caution! This action cannot be undone.