In this blog, I will be discussing the best practice and FAQ to the SAP Ariba API Developer portal and gateway. I will briefly lists the basic overview of SAP Ariba Developer Portal and lists several key process to be considered in order to avoid the common API issues related to SAP Ariba Developer Portal and API gateway itself.
⚡ If you are familiar with the Developer Portal or this blog is TL;DR, you can skip to the Access Token and Rate Limit validation section, which I think is a must read for API developers.
I will divide this into Two sections: Developer portal and API Gateway.
Developer portal:
- As of October 2021, There are several SAP Ariba Developer portals divided into region: United States, Europe, Russia, China, Kingdom of Saudi Arabia, United Arab Emirates, Australia, and Japan. Customer access will depends on which API are going to used and also where the customer realm(s) resides.
- Ariba Network APIs and CIG are only available from United States Developer Portal.
- Customer access are given with registration to the respective portal, with Customers being classified as organizations within the Developer portal. There are two types of users in customer organization: Administrator and Developer users. Customer organization must have a minimum of one administrator user, but additional administrator and developer users are allowed. Typically, Designated Support Contact (DSC) will be assigned the role of administrator users.
- Customer organization's administrator role is to maintain the users of their organization, along with finalizing any API application requests from the developer users by submitting the API application to SAP Ariba for approvals, and when approved, generating the client secret for API consumption. Administrator users can also delete existing application(s) within the customer organization.
- Ariba Network API typically require ANID and the API use will involve configuration within the Ariba Network Admin page. APIs related to specific realms will either be auto approved or enabled by API support team. Some would need to be configured via Intelligent Configuration Manager (ICM) by customer realm administrator Prior to requesting specific API, customer organization must have their valid realm(s) listed with proper name and ANID in the Developer portal.
Frequently Asked Question on Developer Portal:
Q: Can I hire an outside consultant to manage my organization/apps?
A: Initially, only Designated Support Contact (DSC) can be set as administrator user of customer organization. After the administrator has been set up, they can invite members to customer organization and later designate the new member to be an administrator of customer organization. This decision is made within customer organization's discretion, not SAP Ariba. Non-administrator users (developers) within the organization can only create API applications and request for which API the application is for. Activities such as whitelisting IPs, requesting for API approvals, and secret key generation have to be done by the customer organization administrator users.
Q: I'm just testing the API as a partner or consultant, can a customer's realm be added to my organization?
A: No. API application(s) must be created within customer's organization. Access to the app can be shared by the administrator user of the organization to you as their partner or consultant. To their discretion, they can either add you to their organization as regular member, administrator, or simply sharing with you the secret key of the app. This is because the customer is in control of the API access to their realm(s) whether it is their test, production, or development realm.
Q: Can we increase the API call limit for a specific application?
A: The SAP Ariba Customer Support team does not have the ability to increase the rate limit for an API or application. As of 2023, most of SAP Ariba APIs are designed as a back-end integration, not a front end one. Data retrieval should be stored in your local database, not a direct call showing real time data on the fly and repeated for different users/UIs. You might have to spread your calls over some days or weeks if you have a lot of data, so plan for this accordingly.
Depending upon your integration design, your account executive can reach out to the product owner and approval to increase call limit will be reviewed on a case by case basis. Rate limit existed to ensure that your nodes performance are not affected.
Q: Should there be a different API application created for both test and production?
A: Yes. There is a policy which we follow - One application for one realm and one API, which includes test realm. Every application is mapped for a particular API using the application apiKey. So to prevent an authorization error, use different applications for different API.
Q: I completed my development in my test realm, can I migrate the API application for my development realm?
A: No. Separate API Application must be created for your Production realm. The only changes to your development code would be the apiKey in the header portion of the API call and the key used to generate the Access Token. On Reporting API, if view being access require a custom field, recreation of the custom view will be required. This is because custom field name would differs between Test and Production realm.
Q: Are we affected when there is a Certificate renewal on Developer Portal?
A: Depending on your setup to consume the API, certificate update on Developer portal might affect your ability to consume SAP Ariba APIs.
New certificate should be installed prior to the expiration date. One week prior to the update, certificate update notification will be shown upon connecting to Connect Portal and a link to the certificate will be provided.
New in 2023: Please avoid doing certificate pinning as it will no longer supported
API Gateway:
- Access Token validation
Make sure that there is a process in place to handle Access Token validation, this include a process to generate new access token utilizing refresh token and a process that will store timestamp variable to check whether any given token needs to be refreshed prior to making the next/subsequent API call to the final end point. These two processes will avoid 401 error - unauthorized access.
- Rate Limit validation
A process should be made where rate limit available and remaining values(per second, minute, hour, and day) for any given API end points are stored in variables along with the timestamp of the last API call being made. These stored variables must be checked prior to making the next/subsequent API call to the specific end point to avoid 429 error - Rate Limit exceeded.
⚡If you share the apiKey with other teams, these variables must also be updated by everyone who made calls to the API end points using the same apiKey, otherwise your stored variables are not reflecting the real remaining rate limit to the API end point in SAP Ariba API Gateway.
- Header size Limit
As of October, 2021, SAP Ariba API Gateway will only accept a maximum of 4KB or 32kb of data in the Request Header. Complying with this will avoid 502 error - Bad Gateway.Check this blog: How to prevent 502 error with SAP Ariba APIsalso this help manual on Tracing the execution of an integration flow in SAP Cloud Integration
Frequently Asked Question on API Gateway:
Q: Why do I get 403 error: Access Denied. Please contact your Organization admin?
A: This error is returned because the application use the whitelisting IP feature that will block the use of the application unless it is coming from the specified IP addresses. Your organization admin must add the proper IP addresses on the whitelisting IP feature.
Q: Why do I get 400 error - grant type should not be null error?
A: This error is due to the missing grant_type value of openapi_2lo that is required. This value should be spelled out in the body of the request: --data-urlencode 'grant_type=openapi_2lo'
Q: Why do I get error: You cannot consume this service?
A: The cause of this error is the API application attempted to access API end point(s) outside the API that the application was requested for. In other words, wrong apiKey.