Exposing Digital API’s using HCP Trial – API Management Service
1. Introduction
SAP API Management is one of the key enabler to enable a business towards digital economy. Everyone can now explore SAP API management Service as it is also available on HCP trial accounts. For more information about API Management you can use following blogs:
http://scn.sap.com/docs/DOC-65004
2. Story
SAP API Management is so easy and interesting that in a day only i got to know about its capabilities and features. I have created a business case for its better explanation.
In the recruitment process of every organization, HR maintain jobs and enrollments information internally and then manually send it to the job portal websites, but in today’s scenario the eco-system of these portals is becoming huge and diversified that it is difficult to manage everything manually. To simplify this process they can use API Management by which internal resources can get exposed out of an organization network in secured and controlled manner. Application developers can auto discover, subscribe and consume these resources on demand and connect an organization to eco-system of job portals.
Following document provides step by step guidance on how SAP API Management Service can be used to expose such digital information in restricted (like access control on critical information), controlled (like limit on API’s call rate) and secured (like access API’s only by subscription) way. This document also provides detailed process to discover, test and consume these API’s by Developer.
3. Creating API
For instance, There is an OData service which provide job information and can do job enrollment using following OData Service.
https://googlei044067trial.hanatrial.ondemand.com/JobEnrollmentDemo/odata.srv (Basic Authentication with SAP ID Service)
you can also expose this service as Java Application (Java Web Container) in HCP account using following War file
https://mdocs.sap.com/mcm/public/v1/open?shr=l8xlDfCbOlCh07WleEcYTrizBgOZzru36nkBN005r7o
Create Job data using following application URL
https://<application host>/JobEnrollmentDemo/CreateJobs
and I want to expose these OData service as public usage’s API’s.
Open the HCP trial account and activate SAP API Management Service.
Open the SAP API Management – API Portal (for exposing and testing the API’s)
Open configuration Menu, create new system with following details and save (Backed System for provided OData Service)
Host: googlei044067trial.hanatrial.ondemand.com (OData Service URL)
Port: 443 (https default port)
Created system auto generate a new destination in HCP API Portal service. Open HCP cockpit >Service> SAP API Management> SAP API Management API Portal (Roles & Destination)
Configure the basic authentication by providing SAP ID service credential, and HTTPS server trust in destination.
In API Portal Page , Open manage menu and create new api proxy
Provide Following details, Now this API is exposed with name Job_API with “v1/jobpublic” url resource in API management server.
3 Resource for API is auto generated from OData metadata information and now you can restrict the access of API’s like
- I don’t want to expose any analytic information in my API’s
- Job information is read only
You can provide meaningful information to API’s which are easily understandable by developer who can discover and consume this API’s
Open Launch Policy Designer to apply policy in API’s
It seems like API Management doesn’t use HCP destination for making connection with remote service. It only takes host name as an information from the destination. So for authenticating the Backend application, I set Header for Basic Authorization manually in my API policy. For doing so, Created “Assign Message” Policy and added following header parameters.
Authorization: Basic <Base 64 Encoded for username:password>
Accept: application/json (API only support json format)
We can use PreFlow flow type for above policy as this will apply for all the API’s
Code:
<!– This policy can be used to create or modify the standard HTTP request and response messages –>
<AssignMessage async=”false” continueOnError=”false” enabled=”true” xmlns=’http://www.sap.com/apimgmt‘>
<!– Sets a new value to the existing parameter –>
<Add>
<Headers>
<Header name=”Authorization”>Basic XXXXXXXXXXXXXXXX</Header>
<Header name=”Accept”>application/json</Header>
</Headers>
</Add>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew=”true” type=”request”></AssignTo>
</AssignMessage>
Now test the API’s using test tool provided, Open the Menu Test
Apply the Quota policy to limit the usages depending on the product configuration (Will configure later). To apply the Quota policy every API’s need to verify the API key, So add “Verify API Key” policy in preFlow
Make “CheckAPIKey” before “SetHeader” policy in preFlow flow type
Create Policy “Quota” in flow type: preFlow, Quota policy use runtime reference parameter like interval, unit etc from product configuration and then apply to API call.
Code:
<!– can be used to configure the number of request messages that an app is allowed to submit to an API over a course of unit time –>
<Quota async=”false” continueOnError=”false” enabled=”true” type=”calendar” xmlns=”http://www.sap.com/apimgmt“>
<Identifier ref=’verifyapikey.CheckAPIKey.client_id’/>
<!– specifies the number of requests allowed for the API Proxy –>
<Allow countRef=”verifyapikey.CheckAPIKey.apiproduct.developer.quota.limit” count=”100″/>
<!– the interval of time for which the quota should be applied –>
<Interval ref=”verifyapikey.CheckAPIKey.apiproduct.developer.quota.interval”>1</Interval>
<!– used to specify if a central counter should be maintained and continuously synchronized across all message processors –>
<Distributed>true</Distributed>
<!– Use to specify the date and time when the quota counter will begin counting,
regardless of whether any requests have been received from any apps –>
<StartTime>2015-11-11 12:00:00</StartTime>
<!– if set to true, the distributed quota counter is updated synchronously. This means that
the update to the counter will be made at the same time the API call is quota-checked –>
<Synchronous>true</Synchronous>
<!– Use to specify the unit of time applicable to the quota. Can be second, minute, hour, day, or month –>
<TimeUnit ref=”verifyapikey.CheckAPIKey.apiproduct.developer.quota.timeunit”>month</TimeUnit>
</Quota>
With the following re-arrange policy flow, Save the configuration and The API proxy will be ready
Create two products for same API, One for free access with limit of 2 api’s call per minute and other is for paid with 100 api’s call per minute and Publish these products.
4 Consuming API
Your API’s exposed with two different access level depending by product selected by developer. Now open the developer portal from HCP API management service –Dev Portal link to consume these API’s
You can see two products are available , Select the Job Public API’s Free product and subscribe with new application
Create application with name “Free Application”, Application Key and Secret would auto generated.
Copy the application key and test this application using “Test” Menu in dev portal, Provide header parameter: APIKey with application Key and send the api call
Do this call 3 time and you should receive quota error as application is using free API Product.
Similarly create application for Paid Product and do the testing. You will not find any error as application is using Paid Product service.
5. Summary
I hope this short example explained the power of API Management, how to restrict the API’s usage, create quota with different application, expose digital resources in controlled , secured manner and how simple is to discover and consume these APIs using Dev portal.
I am trying to explore other API Management features too, like API’s for REST and SOAP service, oAuth based authentication, message conversion, etc. So stay tuned.
Interesting article with easy steps on How to make use of API management.
My question is: where we have to use auto generated 'application secret' value?
Regards,
JK
It would be used in case of oAuth based authentication to get security token.
Nice blog.
Thank you Vijay for creating this comprehensive blog, around a specific useful business case. I am glad that you were able to learn and deploy something on API Management so quickly.
I notice that you are consuming data from a service that looks like it is deployed on HCP; would you be able to share how people would be able to get this project deployed for consumption as well, so that they could replicate your steps?
I look forward to your next steps on API Management 🙂
Regards,
Elijah
Hi Elijah,
I have provided the Java project war file for testing the OData Service in the blog. Hope it will help to run this exercise complete.
Best Regards,
Vijay
Fantastic, thank you Vijay 🙂
Hi,
I am getting below error while creating API.
I have provided the exact detail as suggested by you.
under URL I I have provided - /JobEnrollmentDemo/odata.srv
Authenticator for authentication type 'BasicAuthentication' needs valid configuration.
Details: Authentication is BASIC, but no user and password supplied.
Can you pls help.
thanks
chirag
Hi Vijay,
While trying this blog I am not getting any resources while creating API proxies. When I clicked DISCOVER, I got an error "unable to fetch from catalog". So, I typed in all the details but again no resources, guess its because my user is not having authorization. I am using an user which can access services from ES4 System. Will that user work for this scenario too or I need to get an additional authorization? If I need additional authorization, please let me know how can I get?
In Destination Configuration, CHECK CONNECTION works fine.
Thanks,
Arivarasu S
Hi Anivarasu,
DISCOVER is only for using Systems connecting to an SAP Gateway backend, fetched from the Service Catalog. In this scenario, you are connecting to a mock OData service hosted on HCP, so DISCOVER will not work.
If you are not getting resources, make sure that you are using ODATA as the connection type, and that you are pointing to the correct base path that has the resources below it (odata.srv). Try calling the endpoint you are adding directly to make sure that you are accessing it properly (Check Connection is more of a ping) as well.
Discovery is the option for system where service catalog are maintianed like SAP Gateway system or PI ESB repository. using discovery you can explore different avalible services.
My example is just simple odata service host in SAP HCP Java application.
Best Regards,
Vijay
Awesome Vijay!
Hello Vijay,
Is that ' Java project war file' still available? Cant find it in mdocs
Regards,
JK
It appears that the share has expired.
Vijay Singh Rajput would it be possible to update the share so that it is available again? 🙂
Regards,
Elijah
Please try now.
Hi Vijay,
the service https://googlei044067trial.hanatrial.ondemand.com/JobEnrollmentDemo/odata.srv
is not available anymore - could you please check?
Thanks for the Blog Post,
kc
Thank for very nice post !
mobile document link is active low