• You may be able to migrate from WSRR to API Connect if you are doing only runtime governance, and not doing design time governance
• API Connect can model your metadata on APIs
• API Connect can be used as an API Catalog
• API Connect offers sophisticated service gateway functionality and rich API analytics
• You can load WSDL and XSD or discover SOAP services in WSRR to define System APIs
• You can use the API Connect Transfer Tool to move sets of artefacts from WSRR into API Connect as APIs
Comparison of API Connect and a Registry and Repository
To learn why you need API Connect, you can read the earlier post, and click here for more details on API Connect.
System APIs are APIs that pass through data from a system of record unchanged. Interaction APIs invoke one or more System API’s or data sources, and manipulate the returned data with new logic.
The free API Connect for Bluemix service enables you to start immediately. For more details, click here.
When you can move from WSRR to API Connect
Given the features of WSRR there are a number of uses that map well onto API Connect, and a number of uses which do not.
Limited design time governance
If your use of a WSRR design time service life cycle is restricted to indicating that a service is being planned, it is being developed, and it has been developed and is available for use, then this maps onto the API phase in API Connect. An API can have one of three states for its phase; Identified if the API is in the early conceptual phase and is neither fully designed nor implemented, specified if the API has been fully designed and passed an internal milestone but has not yet been implemented, Realized if the API is in the implementation phase. The phase is indicated in the API Designer and the API Swagger file.
You can publish a Product containing APIs in any phase to a Catalog and they will be listed in the associated Portal. Note that the Portal does not show the API Phase by default and the module feature “Automatically tag APIs with their phase” must be enabled.
The Portal can be used to socialize details about the API during development.
API Connect is not a document repository and therefore it is recommended to store any documents describing the service elsewhere in a document management system. You can then reference the location of these documents in your API definitions. Alternatively you can inline the document content into the API definition in the description field using Markdown syntax.
Once the API is ready for testing in various environments you can publish it to Catalogs. Each Catalog can have required approvals at each stage; Staged, Published, Deprecated, Retired, Supersede and Replace. You can configure which user roles are able to approve at each stage, and which user roles are able to stage to the Catalog, view the Catalog contents, manage the product life cycle and manage policies.
For more information about API Connect Product lifecycle, click here.
For example, you can configure that a developer can request to stage a Product and API into a Catalog, but an approval is required for the Product to become staged. A user in the Publisher role can approve such a Staging request. Having such a control would be useful for a QA Catalog. By contrast, when using a development Catalog, developers can stage and publish by themselves.
There are no checks for when the phase of an API changes, therefore the checks have to be done manually by an approval when the API is staged or published into a Catalog.
To review a staged but not approved product, you use the API Connect toolkit to copy the Product and API to your local system, where you can then use the toolkit to review the Product and API.
See “Creating and configuring Catalogs” section 7 for details of how to enable Approvals for a Catalog.
WSRR enables modelling of metadata on services, and custom metadata can be added to further describe services.
API Connect can model extensions to the metadata normally provided by the Open API standard using an “extension schema”. These allow extra API metadata to be modelled using the JSON Schema standard, and such extensions are validated according to the schema you provide. The extensions are also rendered in the API designer UI making it easy to add content under an extension.
You can specify the type of data a field is allowed, such as numeric, string or enumerations. An API that contains data for an extension is validated against the extension schema at Stage time and cannot be staged if the API is not correct.
See “Adding an Open API (Swagger 2.0) extension to an API definition (API Manager UI)” in the API Connect Knowledge center.
If you want a Catalog of your APIs so developers can browse, discover and use them, then the API Connect developer portal enables this use case. If you expose your services as System APIs, or proxied services an API, you can publish them to a Catalog and enable them to be discovered.
API Connect allows you to represent your services as System APIs, package them as products and then publish these products into one or more Catalogs. Each Catalog has a developer portal in which the products and APIs are visible.
Full details of each API are provided, and code snippets showing how to invoke the API. A developer can download the WSDL or Swagger document describing the API.
An API can be enforced in which case it is available to invoke through a gateway and consumers can sign up to plans on the API.
An API can be unenforced if you wish to catalog them just for developers to discover them and find the endpoints. An unenforced API is not made available through the API gateway.
Only if an API is enforced through a gateway can a developer subscribe to the API to obtain a key and indicate their use of the API.
With the API Connect 184.108.40.206 syndication feature you can split a Catalog into several Spaces. Each Space is used by a different API provider development team and has its own set of management capabilities for the APIs the team publishes to that Space. This enables each team to manage their APIs independently. The APIs in the Catalog can all be seen in the same developer portal, to provide a unified view of your APIs.
The developer portal can have a custom theme applied to change the look and feel of the portal, to ensure it matches your company design. In contrast the WSRR Dashboard Catalog view does not allow any theming.
The developer portal features forums where each API can be discussed and users can post helpful details on how to use the API, or feedback about the API. The developer portal also features a blog where you can make posts.
See the “Using the Developer Portal” tutorial in the API Connect Knowledge Center.
If you are doing runtime enforcement of your services using a gateway, setting consumer rate limits and checking consumers are agreed to invoke the service, then API Connect is a perfect fit.
API Connect enables you to publish your SOAP or REST Service over HTTP(s) as System APIs with a DataPower or Node.js Micro Gateway enforcing access and rate limits. API Connect is tightly integrated with the gateway, and requires no configuration on either gateway to deploy an API to the gateway.
Out of the box API Connect provides for rate limits on a plan or individual operation level. A product contains multiple APIs and plans. Each plan includes one or more APIs and can set a rate limit for a consumer who is subscribed to the plan, or can override the rate limit for any specific operation.
See “Creating a Product” in the API Connect Knowledge Center for details of setting rate limits on Plans.
API Connect allows custom policies to extend the behaviour and use the full power of DataPower. Once a custom policy has been defined in DataPower and loaded into API Connect, you can reuse it without having to configure on DataPower again.
One such custom policy enables API Connect to invoke an MQ service as the back end of the API. Using this you can expose your MQ services as SOAP/HTTP(s) or REST/HTTP(s) APIs. Click here for more details.
API Connect captures sophisticated API analytics, enabling you to manage service levels, set quotas, establish controls, set up security policies, manage communities and analyse trends. Such analytics are out of the box and require no configuration on DataPower and require no other software to work.
See “Creating and managing visualizations” in the API Connect Knowledge center for details of creating custom analytics views.
API Connect can enforce APIs that expose a SOAP over HTTPS endpoint on the API gateway. The assembled API running in the gateway can invoke an interaction API or backend using SOAP over HTTPS, REST over HTTPS or MQ. The interaction API can then invoke a set of backend services using various protocols.
Therefore if you want to expose a service on a gateway using other protocols such as MQ or File Transfer, then API Connect will not be suitable.
How to move from WSRR to API Connect
To move from WSRR to API Connect for this scenario, consider the following:
• Which WSRR life cycle states you use to track design time states and which API Connect API phases would correspond to these states. For example if you wish to track that a service is being designed and is implemented, these states map to the API Connect phases of “Identified” and “Realized”. If you have more complex states then the 3 phases in API Connect will not be sufficient.
• If you are just tracking development of back end services and not front end applications. API Connect Applications do not have a phase, therefore an Application in API Connect either exists or it does not exist. You cannot indicate that an Application is under development, or deployed, or any other state.
• The standard form of an API that corresponds to a service in WSRR. What metadata does it need? Will it use vendor extensions to capture specific metadata or are the standard Open API fields sufficient? Do you need your System APIs to be enforced by a gateway? What assembly is needed to call the back end?
• Consider which metadata in WSRR you have and where in your standard API definition this metadata will go. For example does the WSRR Service Version name become the API name, will the Service Version description become the API description? Do you need all the metadata in WSRR? Where will you store your documents such as charters, given API Connect is not a document management system?
• Consider which services in WSRR you wish to move across. Not all services may be being used or in production, and you may wish to leave behind any retired services. For a service catalog you may wish to only move across Production services and not services under development.
• Consider which environments you have in WSRR and whether you will map these to one or more API Connect catalogs. For example WSRR Test and Production environments may become API Connect Test and Production catalogs.
• For runtime enforcement, consider which traffic mediation policies you are using in WSRR or directly on DataPower. Can the behaviour of the policies be replicated using the features of API Connect plan rate limits? Are any custom DataPower policies required?
These questions lead to a mapping of what is in WSRR to what needs to be in API Connect. Once you have identified the mapping of WSRR data to API Connect, you can move your services across. This can be done manually or could be automated by using the IBM Service Oriented Architecture Transfer Tool which uses the WSRR APIs to pull data from WSRR and the API Connect Toolkit to push API definitions into API Connect. The Transfer Tool is configurable to take metadata from WSRR and place it in your API definitions.
Finally consider if you will move services that are in development in WSRR into API Connect. It is recommended to develop new System APIs in API Connect and keep developing existing services in WSRR until they are completed, and then move them into API Connect. To move in-development services from WSRR to API Connect will involve far more complexity; the service development process would have to change from a WSRR centric model to an agile API-based approach, and the state of the service would need to be mapped onto the API phase.
Loading WSDL and XSD into API Connect
You can migrate services from a Registry and Repository using the API Connect support for SOAP/HTTPS APIs. API Connect can load WSDL and XSD to define a SOAP API which can be exposed on the gateway. API Connect can also load WSDL and XSD to describe a back end to invoke as part of the assembly of an API.
See “Creating a SOAP API” for creating a SOAP API by loading a WSDL.
The IBM Service Oriented Architecture Transfer Tool can bulk load WSDL and XSD into API Connect, where you have WSDL and XSD for each service and wish to load multiple services in bulk.
If you have a SOAP service in WSRR, then from the API Connect API Manager UI or toolkit, you can search for a WSDL in WSRR and bring it into API Connect and define a new SOAP API. You can filter by life cycle state to narrow down the search to just services that are in production, or test, or any state.
If you are developing an API in API Connect you can again search WSRR to find WSDL services to bring across for use in your API assembly.
If you are using API Connect for Bluemix then the WSRR server must be visible on the internet.
See “Adding a SOAP API definition by discovering a service from a registry” in the API Connect Knowledge Center.
IBM Service Oriented Architecture Transfer Tool
The IBM Service Oriented Architecture Transfer Tool can be configured to move services and metadata across to API Connect.
The tool provides a command-line tool for transferring services and their metadata from WSRR to API Connect. The tool can transfer SOAP and REST services from WSRR and take the service metadata from WSRR: properties, classifications, state. The tool takes a set of services belonging to an organization and transfers them into API Connect. The tool can also take a single service version and transfer it.
The tool can be customized to search for services and metadata in various ways, if you have a custom profile. The tool can be customized to change which data from WSRR is used to create the API definition, if you have custom metadata. The tool will transfer in production (“Operational”) services and applications, and can be customized to transfer services and applications in other states.
The tool can push APIs and Products to drafts and can optionally publish Products and APIs to Catalogs and Spaces.
The tool can find consumers of a service in WSRR and create Applications in API Connect and subscribe these Applications to APIs, to represent the consumers of a WSRR service in API Connect.
Using these features the transfer tool can take in-production services from WSRR and create System APIs for them, taking the metadata from services and adding it to the Open API and Product definitions.
For more details see https://www.npmjs.com/package/apiconnect-soa-transfer-tool and https://developer.ibm.com/integration/blog/2017/10/02/installing-ibm-service-oriented-architecture-transfer-tool-performing-connection-test/.