OpenAPI "first" with SAP PO

[Sebastian76]

Overview

The Open API description standard is by now the most adopted standard for describing APIs.

Nearly any popular cloud vendor, programming language, api management solution or API related tool has support for Open API descriptions and it also could be called the “de facto” standard of the API economy.

Many companies have launched Open API initiatives with the goal to “retire” older integration technology stacks and require backend systems to expose APIs with an “API first” approach, leveraging the OpenAPI "standard".

This blog shows you how to leverage an “API first” approach for OpenAPIs with SAP PO and the KaTe RESTful adapter.

Wait, but we can’t teach an old dog new tricks?

Although there are other newer options on horizon (e.g. CPI, SAP API management, SAP Gateway), SAP PO is (and might be for quite a while still be) used widely as integration layer of SAP landscapes.

Many companies also use some of the available API Management solutions that tap cross domains where SAP ERP (fronted by PO) is one of them.

As we all know SAP PO’s internal architecture originates from the SOA “age” with XML/SOAP/WSDL as internal technology stack. Working with WSDL is straight forward in PO, just import it and work with graphical mappings to implement an integration.

As SAP PO comes with an own REST adapter, even it has improved a lot of features, you wouldn’t have the same “comfort” / productivity there to work with OpenAPIs although the specification itself and many frameworks have the same “comfort zone” (Test tools like Swagger UI, code generators in common programming languages, etc).

Implementing OpenAPIs in a top down approach (API spec first) you would have to go through a few sort of quirks and workarounds (e.g. defining/generating XML schemas from the JSON definitions, switch between messages and ASMAs, massive channel configuration for JSON/XML transformation/error handling) to receive the desired behavior of an API.

Let’s re-imagine we can teach our old dog new tricks and have that at a click of a button like in the “old WSDL times”, but this time as Open API!

SAP PO meets the Open API Petstore Example

For a simple demonstration, let’s have a look at the famous Swagger Petstore example that demonstrates various Open API features.

The Swagger petstore is a demo implementation that showcases various OpenAPI features exposing APIs of the classic Petstore programming example.

We will use the  Pet Store OpenAPI description and expose it with SAP PO and a KaTe RESTful sender channel like in a real “API first” approach you would do with a service hosted in PO.

As "implementation" the Iflow will tunnel all requests to the real Petstore API example via a KaTe Restful receiver channel to also show the opposite use case of invoking a defined OpenAPI.

Both use cases internally will only use SAP PO’s “native” mechanisms like service interfaces and messages and externally the Open API "native" description & Swagger tooling.

Let’s get started

The first step for an API “first approach” is to import an OpenAPI specification into SAP PO.
For that we generate an outbound service interface of the OpenAPI description.

On the adapter UI, we can load the OpenAPI description directly from the Pet Store url to generate a WSDL representing all api actions of the API.

Next we import the generated WSDL just as we would do with a traditional SOAP service, via “Import Service Interface” (here with the "old" Webstart client, sure also possible via NWDS)

The message types represent exactly all request / response properties like headers, query parameters, body and status codes of the openAPI operations.

E.g. here the GET store/order/{orderId} api operation is show with request / response messages with possible status codes and response headers/json bodies.

Now we configure an Iflow with an KaTe RESTful sender channel in “OpenAPI mode” and one KaTe RESTful  receiver channel in “OpenAPI” mode.

The sender sender channel exposes the API under subpath /petstore (as you wold do in any programming framework to define a "basepath" to your API)

The iflow simply routes any call operation to the receiver channel

The receiver channel calls the peststore.swagger.io api host with base path /v2

Magic about to happen, now curtain up for OpenAPIs!

For that simple "tuneling" we are done!

We could now navigate to the adapter UI that displays all published APIs on a SAP PO box.

Both OpenAPI 2.0 (aka Swagger 2.0) and OpenAPI 3.0 descriptions are “auto hosted” by exposing an imported service interface in this format.

By clicking on the links Open API 2.0 or Open API 3.0, the UI shows the integrated SwaggerUI with the API loaded.

Also the OpenAPI specification could be reference or downloaded from here by the link (e.g for usage in a API Management discovery mechanism)

As expected the UI will display the possible inputs and data types of the API operations and the API exposed under the basepath "/petStore" that we configured in our sender channel.

Any exposed API operation could be invoked from here by using the “Try it” button of the hosted SwaggerUI on PO similar as you would on any other API server implementation like e.g. nodejs or Springboot.

Now let’s invoke the POST operation for a pet to create a pet with the example values that SwaggerUI just generates from the defined set of parameters that we can modify for testing:

But you could also have a look at the Schema for further explanation

After hitting “Execute”, the response shows the generated id from the petstore.io implementation we received back through our Iflow. By that we done a full roundtrip of our tunneled API to the real petstore

Hold up not so fast! Now how does that really work?

We didn't fuddle anything on the channels or anywhere else, where did the Swagger UI come from and the API definiton file?

The adapter itself implements a 1:1 translation of Swagger 2.0/Open API 3.0 in form of a WSDL which is forth/backward compatible to the api definition. The generated WSDL represents all api operations with request headers/query/path and body parameters and their possible responses (headers/status/bodies).

By generating/importing the WSDL service interface, the adapter channel could also display it again as Open API description via the self hosted Swagger UI on top of PO.

By that you turn PO into a small "API" box that could self host Open APIs for discovery from API Management solutions or directly as endpoint for smaller contexts.

If a client sends an API call to the KaTe RESTful sender channel, it will auto translate the call to the XML request message as defined by the service interface.

In our tunnel example the receiver channel translates this call back to an API call as defined by the very same OpenAPI specification to demonstrate it works both ways.

The response processing works pretty much the same way.

While of course this is a bit “dumb example” of a simple tunnel, it gives the idea how things work for a 2 way implementation with OpenAPI specs that map to any connected backend technology via SAP PO (e.g.: Odata/RFC/Idoc or ABAP Proxies).

Now let’s have a look how those “openAPI” XML messages look like that carry all information to expose an API structure.

The former POST pet Request looks like this:

which is a POST to /pet with no headers but a json body (here translated to XML by the adapters convention)

The response looks like this

which is a 200 status response containing a json body (here translated as XML by the adapter's convention)

Both structures exist in the WSDL file defined as schema and thereby are validatable, routable or usable in mapping programs internal in SAP PO.

A request could carry any header/path or query parameter / bodies. A response could in return carry any status, header or body. JSON/XML is auto translated without configuring much in a channel.

This is the “secret sauce” behind that allows to act in fully WSDL compatible manner with SAP PO’s internal tooling like graphical mappings while to the outside it looks like pure Open API.

There's no "additional part" of channel configuration that is existing outside the context of the API which needs to be considered in change management (e.g. updating the api or extending it)

Conclusion

This blog post shows an alternative approach on how to expose or invoke an OpenAPI that strictly adheres the defined API specification and KaTe’s RESTful adapter with SAP PO.

This approach works with any typically company wide API Management solution with e.g. auto discovery of APIs and by that is somewhat independent of SAP's offer/roadmap by now.

SAP PO developers can concentrate on the actual implementation details rather then configuration and a lot of extra test work. All of SAP PO’s internal rich features like graphical mappings, validation or routings can be used at the ease as of using WSDL.

Change management of an API becomes very easy as the API description is 100% in sync with its PO implementation without any moving parts (e.g.:JSON or HTTP status code/exception mappings in channels that could go easily out "of band" when doing updates/extensions)

APIs can be created in “API first” (top down) or “ESR first” (bottom up) way with this setup.

APIs are fully documented as exactly as they are at runtime and are directly testable on your "PO endpoints" with the integrated Swagger UI. Consumer application developers, testers or PO developers can test drive APIs through open source tools like SwaggerUI or any OpenAPI compatible test tool (POSTMan, SOAPUI etc) in minutes.

Consumers also can use the extreme rich support of the open source community for code generation and finally API Gateways can simply use any API on SAP PO at a few mouse clicks with full validation features.

 

https://www.openapis.org

https://swagger.io/tools/swagger-ui/

KaTe Restful adapter for OpenAPIs in SAP Appcenter