â€˘ You can expose your existing SOAP or REST services as System APIs in API Connect.
â€˘ You can invoke an existing SOAP service as part of a new REST API.
â€˘ SOAP services stored in WebSphere Service Registry and Repository can be searched and added from the API Manager UI.
â€˘ You can load WSDL and XSD into API Connect to define a System API.
â€˘ You can use the IBM Service Oriented Architecture Transfer Tool to add a set of services as System APIs.
â€˘ When API Connect is using a service you may wish to register API Connect as a consumer in WSRR.
Augmenting Existing Web Services with API Connect
To learn why you need API Connect, you can read an earlier post. For more details on API Connect, click here.
If you are doing design time governance then you can design your services in your Registry and Repository and make them available as APIs in API Connect when they are completed. You use your Registry and Repository to control the development of your service, and then use API Connect to expose the service as an API, or start to build APIs on top of your service.
Such services must be using SOAP over HTTP or REST over HTTP.
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 BluemixTM service enables you to start immediately. For more details, click here.
Exposing SOAP services as System APIs
You may be happy with the definition of your SOAP service and wish to simply expose it as a System API in API Connect, so that it can be enforced through a gateway and the consumers managed in API Connect.
If you have a SOAP service in WebSphere Service Registry and Repository (henceforth known as WSRR), then from the API Connect API Manager UI or toolkit, you can search for a service in WSRR and bring it into API Connect. You can filter by life cycle state to narrow down the search to just services that are in production.
If you are using API Connect for Bluemix then the WSRR server must be visible on the internet.
When you load a service from WSRR, the endpoints are not added to the API assembly. Therefore after you load the service you need to set a proxy policy in the API assembly to call the correct back end.
If you are working on a SOAP service in your Registry and Repository, then you can take the WSDL and XSD and load them into API Connect to define a SOAP API. This can be done in API Connect for Bluemix or the on-premises version of API Connect.
If you want to transfer a set of SOAP services into API Connect as System APIs then you can use the IBM Service Oriented Architecture Transfer Tool.
See the â€śCreating a SOAP APIâ€ť tutorial for creating a SOAP API by loading a WSDL.
See the â€śAdding a SOAP API definition by discovering a service from a registryâ€ť tutorial.
Exposing REST services as System APIs
If you have a REST service in WSRR and are using Swagger to define the service, you can take the Swagger document from WSRR and load it into API Connect using the UI or the toolkit. This can be done in API Connect for Bluemix or the on-premises version of API Connect.
If you want to transfer a set of REST services with Swagger into API Connect as System APIs then you can use the IBM Service Oriented Architecture Transfer Tool.
See â€śAdding a REST API by using an Open API (Swagger 2.0) file” tutorial.
Using SOAP services as part of a REST API
You may have a catalog of SOAP services that you wish to modernize to make REST JSON APIs and then call the SOAP services from inside the API flow.
If you are developing an API you can search WSRR to find SOAP 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.
If you are developing an API you can load your WSDL and XSD into API Connect for use in your API assembly. This can be done in API Connect for Bluemix or the on-premises version of API Connect.
See â€śCreating a REST API definition that invokes an existing SOAP serviceâ€ť tutorial for exposing a SOAP service as part of a REST API.
Finding operational services
Once the service is in production (in the Operational state in WSRR), then you can work in API Connect to define a new API by loading the WSDL from WSRR, applying filters which only show the Operation services in WSRR. If you are developing an API to use parts of the service, you can use the tooling to pull the WSDL from WSRR when developing your API assembly.
You use the filtering capabilities in API Connect to hide any services that are not â€śOperationalâ€ť, thus you can only use in production services in API development.
The service is running in the production environment and therefore the final API can call the production endpoint. When a service is imported in this way into API Connect to create an API, the API has an invoke assembly but the endpoint is missing. The WSRR Dashboard UI must be used to discover the address of the endpoint for the environment. The WSRR Dashboard comes with a â€śService Catalogâ€ť view, which shows services in production and their endpoints.
Testing using non-production services
During development of the API you may wish to call the service running in the test environment. This requires finding the service in the WSRR Dashboard UI and discovering the URL of the test endpoint. The â€śService Catalogâ€ť view shows all endpoints attached to the service, including ones in any environment; therefore the view can be used to find the endpoint for the test deployment of the service.
When the API is developed the API can be published to various Catalogs representing the environments the API runs in, and if the API moves to a different environment then it may be updated to start calling the service deployed in that environment. For example if the API is currently calling the test endpoint and it is deployed to the production environment, it should be updated to call the production endpoint as registered in WSRR.
The API Connect properties feature can be used to specify a different endpoint for each Catalog you have, such that the URL used to invoke the back end service is automatically changed when it is published to each Catalog. Using this feature you can define a property for the service URL and specify its value for each Catalog, and look up the URL for each Catalog from WSRR.
Because API Connect is not a document management system, it is recommended to add entries to the API swagger which link to the documentation stored in WSRR, or use a separate document management system, and point to this in both WSRR and API Connect.
Registering API Connect as a consumer in WSRR
When API Connect consumes a service for use in one or more APIs, you can register the use of API Connect in WSRR if desired.
If you chose to register that API Connect is using a service in WSRR, it is recommended that the API Connect system as a whole is represented as a single consumer of a service, with an appropriate Service Level Agreement to the service. The owner of API Connect should then ensure that the use of the service across all APIs does not exceed the SLA.
This approach is helpful when a central team manages the Registry and Repository, and another team manages API Connect. The approach separates the responsibility for each system. The approach also avoids excessive work to record each and every API created in the Registry and Repository system, and the resulting communication that would have to happen between the teams managing each system.
Thank you toÂ Christopher Phillips for reviewing this blog.