Understanding how APIs Work in Business Accelerator Hub

In this unit, we will explain how the APIs work. The SAP Business Accelerator Hub is the place to find all the APIs for farming processes and services from plan-to-harvest that are available for SAP Intelligent Agriculture.

You can access the SAP Intelligent Agriculture Overview on SAP Business Accelerator Hub here: SAP Business Accelerator Hub: Overview | SAP Intelligent Agriculture

The prerequisites are as follows:

• You must understand what an API is
• You must understand the structure details of the APIs and its prerequisites
• You must understand OpenID Connect Protocol and Password Grant Type topics

In general, when you are working with and consuming APIs from the SAP Business Accelerator Hub, there are basic principles to be understood that apply across SAP solutions and follow market standards. Here are some pieces of important information and prerequisites to keep in mind:

• You must understand what an API is. Refer to the following help documentation on APIs: APIs I SAP Help Portal
• You must understand the structure details of the APIs and its prerequisites. Refer to the following help documentation on API Details: API Details I SAP Help Portal
• You must understand the Using the Resource Owner Password Grant (RFC 6749) with the OpenID Connect Protocol (RFC 7591) topic, since it is they are necessary for authentication and getting the access token to be used in the API requests.
• You must have the following $credentials at hand (example of CURL request):
  Code Snippet

  Copy codeSwitch to dark mode

  1234567891011
  
  curl --silent \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded’ \
  --data-urlencode "client_id=$client_id" \
  --data-urlencode "client_secret=$client_secret" \
  --data-urlencode "username=$user" \
  --data-urlencode "password=$password" \
  --data-urlencode "login_hint=$login_hint" \
  --data-urlencode "grant_type=password" \
  --location 'https://$tenant.authentication.$region.hana.ondemand.com/oauth/token"

Let's look at the API information provided in the SAP Business Accelerator Hub (https://api.sap.com/package/SAPIntelligentAgriculture/overview) in more details.

The overview page provides you with support information such as the component to be used when creating tickets (LOD-AG-FARM), as well as a link to the product documentation.

On the ODATA V4 API, you can see all the services available for SAP Intelligent Agriculture.

As an example, let's look at the Area Service in more details.

On the Overview page, you have access to the business documentation that provides a functional explanation on the attributes and functionalities of this API specifically.

The API Resources include the following:

• API Specification related to the open API protocols
• Authentication Methods used (for example, OAuth 2.0 Application Flow)
• Configuration Details - this is where you can copy the URL to consume this API

The API Reference page shows all the entities available for this service (for example, Areas and Area Types), as well as the operations that can be performed for each entity (for example, Get, Post, Patch, Delete, and so on).

The Schema View provides details on the data requirements to fulfill each attribute and the information that is required to load data.

Finally, the Try Out page enables you to use the SAP Business Accelerator Hub to run requests and test the APIs in SAP Intelligent Agriculture without requiring the application.

Under Select Environment, you can add a new environment to be used.

Before we start, it's important to understand how to read the API information provided on the SAP Business Accelerator Hub.

Let's go back to the Area schema view as an example.

How do you read the API information provided in the schema view?

The Schema View tab provides the list of attributes available for each data entity, including the type of data required and other relevant information.

For example, the 'Name' attribute requires string data that can have a maximum length of 255 characters. On the other hand, 'validFrom' requires string($date-time) data and an example of the expected data is provided.

To identify whether an attribute is mandatory (when creating a new record for example), you need to check the attribute information:

• nullable: true = Optional
• ﹤no information﹥ = Mandatory

For example, 'Name' is mandatory, while 'validFrom' and 'areaSize' are optional attributes.

The same concept applies to the Entity Dependency, which means an attribute may require an entity to have been pre-created. For instance, 'areaType_ID' requires a uuid to be provided, so the Area Type should be created before the Area entity.

To identify whether an Entity-Dependency is mandatory, you need to check the information in the Schema View tab.

• nullable: true = Optional
• ＜no information﹥= Mandatory

For example, to create an Area the 'areaType_ID' attribute is mandatory, while the 'areaUOM_ID' is optional.

Now that we understand the prerequisites and how to read the APIs in the Business Accelerator Hub, let's look at how to consume the APIs.

• Authenticate
  • <USERNAME> and <PASSWORD>
  • <CLIENT-ID-FROM-BROKER> and <CLIENT-SECRET-BROKER> from the BTP subaccount
• Get the Access Token
• Run the API Request (Get, Post, Patch, etc.)

You can use various tools to consume REST APIs. As mentioned, you can try out the SAP Intelligent Agriculture APIs using the SAP Business Accelerator Hub (https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/trying-out-apis) for sandbox or productive systems, and see how they work.

Alternatively, you can test the APIs using CURL (https://curl.se/), Insomnia (https://insomnia.rest), or any other tool of your choice.

For the purpose of this e-Learning, we will use the simplest tool (CURL), which is a pure text-based tool and will make it easy for you to understand the commands and ultimately convert the CURL request into another language of your preference (if needed).

There are 3 basic steps to consume the APIs:

1. Authenticate
2. Get the Access Token
3. Run the API Request (Get, Post, Patch, and so on)

123456789
curl --request POST \
--header 'Content-Type: application/x-www-form-urlencoded’ \
--data-urlencode 'client_id=﹤CLIENT-ID-FROM-BROKER﹥’ \
--data-urlencode 'client_secret=﹤CLIENT-SECRET-BROKER﹥’ \
--data-urlencode 'username=﹤USERNAME﹥’ \
--data-urlencode 'password=﹤PASSWORD﹥’ \
--data-urlencode 'login_hint={"origin":"sap.custom"}’ \
--data-urlencode 'grant_type=password’ \
--location 'https://﹤TENANT-NAME﹥.authentication.eu10.hana.ondemand.com/oauth/token’

1. Here's an example on how you can execute a GET Request using a CURL command:"https://﹤TENANT﹥.﹤ORBIT﹥-﹤REGION﹥.ia.agribusiness.cloud.sap/api"

   Export the environment variables (example):

   • export TOKEN="﹤ACCESS-TOKEN"﹥
   • export ENDPOINT=" https://{baseUrl}.cfapps.{region}.hana.ondemand.com/api/farm-and-field-api/v1/odata/v1/FarmAndFieldService/Farms"
   Note

   • "﹤ACCESS-TOKEN﹥" – copy the access token field that is returned after running the command mentioned in Step 2.
   • https://{baseUrl}.cfapps.{region}.hana.ondemand.com/api/farm-and-field-api/v1/odata/v1/FarmAndFieldService/Farms – The API URL can be obtained in the SAP Business Accelerator Hub under Overview -﹥ Configuration details, as explained in the previous unit.

   Execute the request:curl --request GET --header "Authorization: Bearer $TOKEN" --location $ENDPOINT

2. Here's an example on how to execute a PATCH Request for creating a new farm using a CURL command:

   Export the environment variables (example):export TOKEN="﹤ACCESS-TOKEN﹥"export ENDPOINT="

   https://{baseUrl}.cfapps.{region}.hana.ondemand.com/api/farm-and-field-api/v1/odata/v1/FarmAndFieldService/Farms(FARM-FIELD)

   "export DATA='{"description": "Farm test 1"}'

   Note

   • "﹤ACCESS-TOKEN﹥" - copy the access token field that is returned after running the command mentioned in Step 2.
   • https://{baseUrl}.cfapps.{region}.hana.ondemand.com/api/ farm-and-field-api/v1/odata/v1/FarmAndFieldService/Farms" - The API URL can be obtained in the SAP Business Accelerator Hub under Overview → Configuration details, as explained in the previous unit.

curl --request PATCH --header "Content-Type: application/json" --header "Authorization: Bearer $TOKEN" --data $DATA --location $ENDPOINT

The SAP Intelligent Agriculture Team has developed a simple tool that provides a step-by-step guide on how to consume the APIs.

The API Shell Suite for SAP Intelligent Agriculture is accessible here: https://github.com/sap-contributions/api-shell-suite. It will be explained in further details in the next section.

Manual Execution Option: https://github.com/sap-contributions/api-shell-suite/tree/main#manual-execution-option

Within the API Shell Suite, the manual-execution-apis folder (available here: https://github.com/sap-contributions/api-shell-suite/tree/main/app/manual-execution-apis), contains a set of files that are designed for manual copying and executing in your tool of choice (for example, CURL).

You can go through each file and command, understand its purpose, and execute it step-by-step to consume the API. Always ensure you understand the implications of a command before executing it.

Open the Farm.sh file to see an example on how to run a GET request for the Farm & Field service API.

The first 2 steps support authentication into the system, as previously explained.

• Step 1: is about setting the Username and Password credentials
• Step 2: is for entering the Client ID, Client Secret and tenant parameters

  → Simply copy the commands in each step and replace the placeholder information with the relevant information for your case.

  When this is authenticated, you need to get the Access Token by copying the exact commands in steps 3-5 sequentially.

  When the Access Token is granted, steps 6-8 outline the commands necessary for running the GET Request.

• Step 6 is composed of a variable: api_url and a string: https://{baseUrl}.cfapps.{region}.hana.ondemand.com/api/farm-and-field-api/v1/odata/v1/FarmAndFieldService/Farms.

  The API URL can be obtained in the SAP Business Accelerator Hub under Overview → Configuration details, as explained in the previous unit

• Step 7 is about executing the GET request.
• Step 8 is about showing the results obtained from the GET request, which in this case will be the list of farms available in the system.

You have now seen how to consume an API. Let's move on to loading data in the system.