How to find/create suitable APIs for your extension and integration needs?

[mlauber]

In my recent work for Clean Core with customers, I often get this question: which Standard API can/should we use for [X]? A simple question and maybe not a super simple answer. How can you find APIs that suit your requirement? Below I list some options that hopefully help. And further below I'll also talk about how to create your own API, should there be no suitable standard one.

Edit history:
2024-10-30: I added how to check the release contract for remote API (C2) for the API-CDS in chapter 2.1.2

2024-11-05: I added more info about released APIs and Tier 2 option, when an API is not released

1 Find the API via Business Accelerator Hub 

My best tips for searching on the hub is to first select your SAP product from the homepage, such as SAP S/4HANA Cloud, private edition, and so on. Next click on the APIs tab and in the tabs that open below, click on All (or specify the type of API if you are in need of a certain one, such as SOAP). After that, try and search for the main business context/object for which you need the API. Say for example that you need account assignment information of purchase order items. Instead of searching for account assignment or even items, you search for the main object: "Purchase Order". Another example, slightly trickier; say you need company code information of a customer, then you don't search for "company code info" or even "payment terms", but instead you search for "Business Partner" (and not customer). Business partner here is the main object that holds the main general information, whether that's for suppliers or customers or persons. At this point you cannot know if the Business Partner API contains all info you need for your customer-related API, but this is usually the best way to start and check. Let's use this example for the next step:

1.1 Make sure the API includes the data you need

When you found a possible API, before writing it down into your specification and call it a day, make sure it provides what you need. On the hub, simply click on the API and, if you are not logged in or have no system information saved, ensure you choose your correct release in the upper right part.

Next, check the Schema View and make sure all your needed data is available (if needed expand into field level if you must have certain fields):

We can see that the business partner API has both, customer specific data and also company code data for customer. Hooray, we found the right API! But hey, I may need to update customer company code data in my case, so let's make sure the API offers that as well. We often see that on the schema too, for there are different schemas depending on the operation:

On the API Reference tab, we can look at the operations in detail:

2 No suitable API found on the hub...

What if you could not find a suitable API on the business accelerator hub (and I'm gonna be honest here, I sometimes have troubles searching there as well)? Let's continue the previous example. Say I also wanted credit segment and limit information of customers. When I checked the business partner API, I could not find credit information in the schema view. Meaning I need another API. Now I said before to search for the main object always first. In this case this is still "customer" or "business partner" and we already checked that. Next I looked for "credit segment", and also "customer credit" but I couldn't find anything that matched. So, what other ways do we have to search? One way could be to ask your partner/functional expert and see if they happened to know. If not, ask yourself, where is the data coming from? Is there maybe an app that shows it? If yes, we have our next option...

2.1 Find an API via an app

Start by going to the Fiori apps reference library. This is always your place to be for any app check. Select your SAP S/4HANA version and find your app. If we continue our example, it would be Manage Credit Accounts:

Once again before you proceed, ensure you have your release selected in the drop-downs at the top. Next, select the IMPLEMENTATION INFORMATION tab and scroll down to OData Service(s). Please note that more than one could be listed here, but there is always a "main" service, which contains the main business context. It shouldn't be too hard to discern which one it is, or if it is, ask a developer for help.

Now it's important to understand that this isn't it. UI services are exactly meant for that purpose: for the UI, meaning for an app. These services should not be used in extension- or integration scenarios, where we do not work in an UI (if you have a UI extension need, then possibly this service could be the right one, but for this blog I focus on non-UI scenarios). But, we are here for a reason, because knowing this service can tell us the underlying data layer, which in turn can help us to find an API with the same/similar data. Let's get to it.

2.1.1 Analyze a UI service in ABAP Development Tools for Eclipse (ADT)

Copy the name of the OData service from the Fiori library and open your ADT. If this is turning too technical for you, you may want to ask a developer to help with this 😊.

In ADT we can open any ABAP repository object with the keyboard shortcut Ctrl + Shift + A. Press it and enter the name:

Few side-notes: I am using dark mode in all my tools these days (I can highly recommend it, it's so good for the eyes), so yes, what you see above is indeed ADT. Next, your dialog may look slightly different, for example without the dotted line: this line indicates objects I had recently opened (ADT helping you to find and re-find your objects fast).

In the result that appears, be sure to select the one with the green icon and explanatory text "Service Definition". When looking at said service definition, you will see all exposed CDSs of this service. Now it can get a bit tricky and may need several tries. We need to find the CDS that contains the data for our API need. Again, my usual try is to open the "main CDS", which is very often the one listed on top. Simply place the cursor on the CDS you want to examine, and press F3, which will open it.

2.1.2 Analyze CDS view and data to find API

From here I read and check the data (I may need to dive deeper by accessing more CDS with the F3-opening) to make sure I have what I need. In my case I opened the R_* view entity and on it I found what I needed:

Now it is difficult to teach this and with experience these tings will go more smooth. In chapter 3 I will talk a little about the View Browser app which maybe is a little bit easier at first. Personally I go for ADT first, because I have access to all objects.

So we've identified the CDS view (or views), how can we see if there is an API with similar or exactly that data? First of, knowing the VDM (Virtual Data Model), CDS naming conventions (Naming Conventions for Development Objects | SAP Help Portal) and how RAP business objects are built is key. When we know it, we know that the R_ view is the base CDS view. We have two options; we could do a where-used-list on this R_* view and see if we find more projection views (again, knowing RAP here is important, I won't go into detail here), which we then can also "where-used-list" to find the service definitions they are on. Or, what I find faster, we can look for the "view created for the API purpose". Meaning a view starting A_ instead: those are the names of CDS views meant for APIs (most of the time, not always). So, we can once more make use of the powerful search of Ctrl + Shift + A:

As you can see above, I searched with the exact naming of the R_ view, but instead starting with A_. Now, this will not work 100% but again, the searching in this dialog view is really powerful. We can search using asterix (*) and we could for example also consider searching the Credit Management Account CDS view I found previously. For example "A_*Credit*acc*" or again, using the same short version for "credit" as in our R_ view "A_*crdt*" and so on. Now in my example we found the data definition we will probably need. So I opened A_CrdtMBusinessPartner and immediately saw that it indeed gets its data from R_CrdtMBusinessPartnerTP, which is the CDS view the app also uses (the where-used-list on the R_* would also have shown this, if we had gone that way).

To be clean core compliant, which means to only use released objects, before we proceed we should check the released contract of the CDS A_CrdtMBusinessPartner. For API related objects, we have the release contract C2, Use as Remote API:

If the API is not released, not all is lost. We can then resort to what we call Tier 2 in clean core extensibility and development model. Assuming the above CDS was not released, what you would do it to create a custom CDS in your custom namespace. This CDS should do nothing else but get its data from the standard CDS that was not released; this is called creating a custom wrapper, around the unreleased SAP object. Once done, you will yourself release your custom CDS, in this case with the C2 contract. Then you will proceed to create the proper service definition and binding, and in the end, in your extension scenario, you would then use your custom service that was built through the wrapper. Such developments are marked as Tier 2, with the idea to replace them with SAP standard, once the standard object has been released. To help with that, you can create and/or search and engross existing customer influence, see more here Customer Influence and Adoption | SAP Community.

Back to using the released standard CDS. As a last step, now that I have the CDS that is meant for API exposure and which is released, I can do the where-used-list here to find the service definition:

From the service definition we do one more where-used-list to find the actual API. Often they have the same name, but not always. For example the real service could contain the protocol in its name, such as _O2 or _O4 for the OData protocol and the version. In our case, they had the same name:

3 Find CDS views with the View Browser app

Another way to go about this is to use the View Browser app. You will need a role based on SAP_BR_ANALYTICS_SPECIALIST to access this app in your system. Here we can search for CDS views, so we can use this if for example if we have no app, or if we are generally unsure. Now I don't recommend scrolling through here, there are thousands of views listed. Instead we could try free text searching, for example:

We can see we find a similar CDS as we did in chapter 2, but not the exact same. As mentioned before, not every single CDS is listed here, which is why my own preference is ADT. But View Browser has a neat little feature if you happen to know either the database table or a field that you need to have on the CDS. Then we can use the Alternative Search button. For business partner credit segment data, the DB table is UKMBP_CMS_SGM:

From here, once we have a promising CDS, we would go back to step 2.1.2 Analyze CDS view and data to find API.

4 No suitable (or only partial) Standard API found - what now?

If we gave our all (of course) to find a standard API for our requirement but were unsuccessful, or we found one that has most data we need but not all, we have several options. Depending on your exact use-case and also your SAP product, more or less options are available and some options may make more sense.

• If you found a Standard API but it's missing some data, you have two options:
  • If the missing data is new custom fields you had added into the business context, then return to the Custom Fields app and enable those custom fields on the APIs tab, for the API you found
  • If the missing data is other, existing data you can see if the API is extendable with Custom Fields - Data Source Extension.
    
    
• You found no Standard API or only those with few of the data you need:
  • Use Custom CDS Views app to combine existing CDS views (standard and custom) into one view for API exposure by choosing scenario External API
  • If you are on SAP S/4HANA private cloud, on-premise, or on public cloud with a 3-SL setup, then you can ask a developer to create a custom RAP object with API exposure. Or your developer creates just custom CDS view(s), which you then use in Custom CDS Views app to combine with standard.

5 Once you have your suitable API

APIs are not exposed by default. Those you want to use, you need to prepare first. Here again things differ whether you are on a private cloud or on-premise system, or public cloud. I won't go into details in this chapter, there are already good guides and tutorials out there, but just to outline the final step, before you can use the API:

• SAP S/4HANA Cloud, private and on-premise editions:
  • The API service needs to be activated so that it can be used. The activation depends on the protocol of the service:
    • OData V2: use transaction /IWFND/MAINT_SERVICE
    • OData V4: use transaction /IWFND/V4_ADMIN
    • SOAP: use SOAMANAGER
      
      
  • If the API needs to be used outside your system, you need to ensure that your Cloud Connector configuration allows your API, or otherwise whitelist it there.
  • Now the API can be used and called
    
    
• SAP S/4HANA Cloud, public edition:
  • First of, trust needs to be established between your public cloud instance, and the target system: create a communication system via Communication Systems app
    • This may require the setup of a communication user or propagation-type setup, as per your requirement and security needs
      
      
  • Next, you need a communication scenario to include the API:
    • If you found a standard API, you need to find the standard communication scenario in the Communication Scenarios app (often this information is also documented in a SAP Help page for the API or on the HUB, if you found it via the hub).
    • If you created your own custom API, you need to create a communication scenario for it, with Custom Communication Scenarios app. One scenario can contain several APIs, if applicable.
      
      
  • Lastly, you need to create a communication arrangement, in the Communication Arrangements app. Each is linked to one communication system and one scenario, created in the previous steps. Only once the arrangement is fully configured and activated, can the linked communication system access the APIs listed in the communication scenario.

Conclusion

There are many APIs delivered by SAP. We always recommend to try and use SAP Standard, whenever possible, so learning how to find APIs is an important skill. You also have the option to reach out to one of your SAP counterparts to help you out, if you should get stuck. And I also therefore kindly ask you not to ask me on this blog here, to find APIs for you, that could become a little overwhelming. But if you have general questions on how to search, or comments, I'm very happy to read them and offer my thoughts.

Happy API-ing 😁