Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   
 

Service Management

Nov 12, 2013 19:05

Robin Pille

Aug 01, 2014 00:35

Mulesoft Current Mule Documentation

Service Management

Mulesoft Documentation Page

Contents

Service Management

Deprecated Version

You've landed on a page for a deprecated version of the Anypoint Platform for APIs. If you are currently using this version, please migrate to the current version of the platform.

 Contents

 

A service, as defined in API Manager, can be an API or a web services of any kind, or a group of APIs, and can be hosted either on premise or on the cloud. The user who registers a service in API manager via the web application or the REST 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 API Manager's cloud-based repository confers a number of benefits to the organization as a whole by facilitating effective 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 API Manager web application. Note, however, that you can also perform all of the same operations via the API Manager REST API

 

Registering a Service

Complete the following procedure to register a new service in API Manager.

  1. Click the Services icon in the top navigation bar, then click Add Service.



  2. API Manager 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.

    FieldBest Practices
    NameEnter a name with only upper and lowercase letters, numbers, spaces, and dashes. No other special characters.
    SummaryEnter 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.
    DescriptionEnter 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.
  3. In the Version Details step, fill in the required details according to the table below, then click Next Step.

    FieldBest Practices
    MajorMajor component of the version number. Must be an integer.
    MinorMinor component of the version number. Must be an integer.
    RevisionRevision component of the version. This field accepts any string.
    Release NotesOptional. 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.
  4. 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.)
  5. In the three-step Add 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.)

    FieldRequiredBest Practices
    URLYes

    Specify the full address of the inbound endpoint to which consumer service calls should be directed. The following endpoint types are supported for all API Manager features:

     http/https 

     file 

     ftp 

     jms 

    • vm

    You can specify any valid internet protocol, but note that other protocols have not been validated to work with all API Manager features.

    Note that you will not be able to edit this field later, so if you need to change the URL, you should delete the endpoint with the old URL and add a new endpoint with the new URL.

    StatusYesThis 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.
    EnvironmentYesThe 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 by organization owners via the Administration menu.)
    AliasesNoYou can define one or more alias URLs here for your endpoint. Aliases allow you to manage your endpoint through a load balancer or proxy. Aliasing also allows you to manage multiple localhost endpoints with the same name in your organization. Read more about endpoint aliasing.
    Metadata Key and ValueNoYou 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.
  6. 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.



KeySpecific toDescription
1Service profileService

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 API Manager 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.

2Release notesVersionClick 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.
3Ratings and ReviewsVersionClick 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).
4Tags and TaxonomiesServiceAny 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.
5Version information tabsVersionNote 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.
6Service menuServiceThe 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.
7Version menuVersionThe 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.
8Version information paneVersion

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.

9Service information paneServiceThe 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.
 What do other users see?

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. API Manager 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.

Managing Endpoints

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.

  • 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. 
  • 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 aliases and metadata.

Endpoint Aliasing

Endpoint aliases must be valid, unique URLs in your organization. Thus, if your main endpoint URL references localhost or an IP address, the aliases defined here allow API Manager to route service calls to the correct service, even if another user uses the same localhost URL for his or her service. Aliasing also facilitates load balancing, proxies, and mapping to multiple IP addresses.

If you use the auto-discovery functionality to register new services and endpoints, the API Manager agent is able to discover aliases automatically upon deployment in some scenarios. If you deploy an application with localhost endpoints, and you are binding to all network interfaces in your machine, API Manager will create one alias endpoint URL for each network interface it detects. 

Endpoint aliases work slightly differently for services hosted on CloudHub, or proxied to a CloudHub-based API Gateway. Services that use CloudHub are built using ${http.port} property placeholder to allow CloudHub to dynamically assign a URL based on the domain assigned upon deployment. In this case, if you deploy using the auto-discovery functionality to the CloudHub Mule Runtime December 2013, API Manager will automatically replace ${http.port} with 8081 as the primary endpoint URL. In addition, API Manager will display the CloudHub domain address for your endpoint instead of the localhost address.

Endpoint Metadata

Metadata makes 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: 

EndpointMetadata KeyMetadata Value
Endpoint 1regionAmericas
Endpoint 2regionAPAC
Endpoint 3regionEMEA

Or, if you want to route consumers to different endpoints based on their business unit, you might add metadata as follows: 

EndpointMetadata KeyMetadata Value
Endpoint 1BusinessUnitAccounting
Endpoint 2BusinessUnitSales
Endpoint 3BusinessUnitOperations

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. 

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.

Managing Artifacts

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. API Manager 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 API Manager 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. API Manager 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. 

 

Go Further