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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
Find APIs
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.
Documentation
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.
- SAP Managed Tags:
6 Comments
