SAP API Management – a full overview (2)
In the first part of my blog, I started explaining the components of SAP Cloud Platform API Management, as well as how you get started.
In this second part, I will focus on the pre-defined policies and on the Developer Portal.
Configure, don’t code
Once an API proxy has been defined, its runtime behaviour can be influenced in many ways.
SAP API Management relies on the idea that our customers need to run simple. Hence, SAP API Management is using a graphical interface to allow API builders to design how existing APIs are being made available. This graphical interface is the policy designer.
The policy designer is a graphical interface which uses a pipeline representation (request-response pattern) where pre-defined policies are being positioned to perform various tasks such as verifying an API key, limiting the inbound calls or caching the response data.
This helps administrators to quickly publish APIs, on an error-prone way, without programmatic knowledge and in a understandable, graphical fashion.
Efficiency through pre-defined policies
The requirements for API Management are recurring so that a large amount of features is pre-defined (as described above). These pre-defined policies, can roughly be grouped into 4 categories:
- Security: secure your API access through security policies on every level: network level, message level, user level.
Example: you may want to authenticate API consumers through typical web-based security mechanisms like OAuth or SAML tokens. This allows for various authentication scenarios that may be required by different API consumption use cases.
Furthermore, you may also want to inspect the messages flowing towards your API implementation in order to enforce threat protection (client side injection).
Another way to protect against malicious attacks is to enforce IP-filtering through IP-blacklists and -whitelists. This can easily be configured using the “Access Control” policy.
- Traffic Management: protect your backend systems against high amount and concurring requests.
Example: you may not be able to serve more than 100 request per second from your backend System. Instead of allowing the request to even hit your internal network, you may want to add a “Spike Arrest” policy in the API Management Layer.
However, even with a bandwith-limited system, thanks to the Caching policies, Information can be held in the API Management layer to be served faster than from your internal system.
- Mediation: transform the data that flows from or to your actual API implementation.
Example: you may want to provide customer information to your business partners, however you want to filter out information based on the partner type. Instead of creating and maintaining several API implementations in your system, you can do the filtering dynamically within SAP API Management.
Furthermore, you may also want to harmonize the message format that is provided by your APIs to simplify their usage. For instance, you may decide that all APIs should use a JSON message format. Instead of reengineering all REST API and SOAP WebService implementations, you can do the XML to JSON transformation in the SAP API Management layer.
Another typical scenario would be to mash-up information in SAP API Management. For instance, you may provide addresses through one of your systems, however a developer needs geolocation data (coordinates) or weather data for that address. You can easily add this data into the response message of the API, without touching the backend API of SOAP WebService.
- Extension: create your own specific API runtime behavior by coding it.
Example: you may want to fine-tune the behavior for your API with very precise features like passing calculated parameters based on the incoming message to an API backend system.
Or you may want to make a specific message information, such as the requested product name, available in the analytics to create business reports.
Using pre-defined policies, securing, adapting and customising APIs now takes place in the API Management layer, simplifying the work for both API Management Admins and API Developers.
Furthermore, using the “policy template” feature, customers can create a set of policies once, and re-use them multiple times.
This allows to easily implement an enterprise-wide governance model to streamline security and publication of APIs.
Publish your APIs: Developer Portal
Once APIs have been configured in the API Portal, they can be used by the Developer who will build the Application, App or Integration using these APIs. However, there is a huge difference in “somehow” making these APIs available, and publishing them in a self-service, documented and controlled way. This is where the Developer Portal is extremely important on your journey to a single pane of glass for the entirety of your APIs.
The Developer Portal is the single point of access for the entirety of your APIs. This is where Developers come to when they need to find, test and subscribe to APIs.
The Developer Portal is tightly integrated into the API Portal (where you define the API proxies): it is just a matter of bundling API together and hitting a button to publish these to the Developer Portal.
This tight integration allows to drastically reduce the time and effort to provide APIs to your developers in a modern and low-touch way.
Self-service for fast onboarding
Developers building applications using your APIs can be internal, business partners or a technology partners: you do not know all developers upfront, but you still want to provide them APIs in the most cost-effective and fastest way.
Therefore, the Developer Portal provides a self-registration (with approval step) capability. Hence, there is no upfront lengthy onboarding process for your developers to get access to your APIs, which is the first step towards a good “Developer Experience”.
Allowing application developers needing your APIs to be self-sufficient from step one, will largely simplify and speed-up their engagement process, and reduce effort and costs.
The Developer Portal is the single point of access for your APIs. Application Developers, once registered, can browse or search for the APIs they need in a simple and modern way.
Note that the API Business Hub is based on the SAP Cloud Platform API Management Service, hence providing the same look-and-feel.
Allowing application developers to search and find APIs on their own will free up time of your internal staff: they will not need to go into lengthy discussions anymore, to understand the application developer’s needs and to propose them the best suited API.
Because developers should be working autonomously, they need good documentation. If metadata is available, the documentation of an API is created in an automatic way: OpenAPI specification (fka. Swagger) can be read and imported into the API (as well as RAML), and the same happens when using an SAP Gateway as API backend system or when using OData REST APIs.
In any case, documentation can be refined or created from scratch, using the embedded HTML Editor of the API Portal.
With SAP API Mangagement, not only the API is made available to Application Developers: the API comes with documentation pulled automatically from the API itself, which can be enriched with specific information. This largely helps Application Developers to be very efficient during development reducing development time.
Unlock insights with the API Key
Once Developers have explored your APIs, they want to start working with it. In order to enable access to these APIs, Developers will “Subscribe” to them. Doing so, they will get an API key.
An API key is the best mechanism to identify an Application, its Developer behind it, and the API Calls that are made. Simply put: API key is not mandatory but will unlock great insights in your API and application landscape.
Using API key you are always in control.
- in case you make changes to an API, you can contact all Developers using this API,
- in case you see erroneous API Calls from an Application, you can contact the Developer,
- you can identify successful and less successful Applications and their Developers to take appropriate actions within your Digitalization Program,
Using SAP API Management, you are now able to really understand what is happening with your APIs in order to increase Developer Experience. You can also precisely steer your API program to avoid unnecessary costs and invest in successful areas.
In the next part of this blog series, we’ll focus on the details of analytics and integration into other SAP services.
Thanks for that Sven,
API Management is a compelling offering. Especially the feature by which upon registering an OData service, API Management is making available the API specification as OpenAPI 2.0 and provides the usual 'Try out' test options we're used to from Swagger.io.
Making an attempt to register a real-world OData service as an API today though we noticed that (after successful OData discovery and metadata load) API Management does NOT recognize resources when inspecting the OData service metadata ('Resources' tab is hence empty).
Would you know what the issue is here?
Thank you for commenting.
thanks for your feedback!
As you know, it is difficult to support remotely. Personally, I have been testing OData API Proxies against SAP Odata and the Northwind (https://services.odata.org/V2/Northwind/Northwind.svc/) endpoints only. In both cases I had no issue with discovering the resources.
Could it be that the metadata is malformed or that the definition of your API Proxy is incorrect?
Here is one example using Northwind:
And here the API Proxy:
In case your API is publicly reachable, I could have a look at it.
Otherwise, in case you have an OpenAPI description (fka. Swagger) of the REST API, you can use it too, to get the resources.
Sorry I can't help more than that for now!
after a while of investigating further I figured out that API Management was behaving correctly when interpreting the OData metadata. It turned out that none of the entity sets to be exposed were flagged to be 'Createable', 'Updateable' etc. So after setting relevant attributes this in the backend system using SEGW as follows:
I then correctly got the OData service exposed on API Management:
Thanks for getting back to me,
Interesting read, I have a question related to Traffic management. Can API Management serve as a load balancer, distributing messages to several CPI tenants?
API Management cannot do typical load balancing - simply because you don't need it!
API Management and Integration are both behind load balancers so that you only need to focus on building your integration or app - not on the infrastructure.
However, API Management is capable of routing, yes: you can define to what system you want to send a request. This is done through route rules as described here:
I have a question, is it possible for me to maintain 2 separate API artifacts and at the same time display them as 1 reference documentation in API Developer portal with 2 different API proxies within the same document?