Module 2 Lab 1 - Design the SAP S/4HANA System API
Overview
In Module 1, we implemented the SAP ECC System API using an already published API specificaton. But how are such API specifications created? The focus of this module is learning about how to design and create a new API specification. We’ll look at API Designer and build API fragments which are resuable components of RAML to make the design and build of a reusable API even quicker and easier. Then we’ll implement a Mule application for the newly create API specification and learn how to connect to SAP S/4HANA using the OData connector from Exchange. Lastly, we’ll take the Mule application and deploy it to CloudHub.
So let’s take a look at what we’ll be covering in this lab:
-
Create a common data types library fragment which we’ll reuse in an API specification.
-
Create the API specification for the SAP S/4HANA System API
-
Publish the API specification to the private Anypoint Exchange
Step 1: Create a Common Data Model Fragment
Fragments are a great way to set standards. Such as common data types or traits which can be reused by others inside your organization.
1.1 Go to Design Center
Log in to Anypoint Platform and click on Start designing under the Design Center section.
Anypoint Design Center is used to design your APIs and Fragments. When you arrive at the Design Center landing page you will see a list of APIs that have already been designed in your organization.
To create a new API fragment, Click on the Create new button on the top right and click on New Fragment
-
Set the following values in the form:
-
Project Name: <your initials>-Datatypes
-
API specification fragment format: choose 'RAML 1.0' and from the drop down menu,as fragement Type, select : Library
-
-
Click on Create Fragement
|
Since we are working in a shared organization, please give your API a unique name. For the purposes of this workshop, please prepend your fragment name with your initials or Anypoint account username. |
-
Copy the snippet below and paste it into your worksheet
#%RAML 1.0 Library
types:
address:
properties:
type?: string
street1: string
street2?: string
street3?: string
city?: string
zip?: string
state?: string
country?: string
addresses:
properties:
billing?: address[]
account:
properties:
id?: string
externalId?: string
source?: string
lastModifiedDate?: string
accountName?: string
addresses?: addressesWe are defining the datatypes
-
address
-
addresses → inheriting an array of datatype address
-
account → inheriting the addresses object
Publish your newly create fragment to Exchange so we can use it in our next steps
-
Please provide a version number eg. 1.0.0
-
Click Publish to Exchange
The API fragment is now successfully published to Anypoint Exchange. Next we will reuse this API Fragment as we work on the API specification of the S/4HANA System API
Step 2: Create the SAP S/4HANA System API specification
Navigate to back to Design Center and click Create new on the top right. This time, click on New API Spec
In the pop-up window, set the following values:
-
API Title: <your initials>-SAP-S4HANA-sAPI
-
How do you want to draft the API Spec?: I’m confortable designing it on my own - RAML 1.0
Click Create API Spec
An empty worksheet is now created for you. In order to use the fragment that we created in the previous step, let us import it as a dependency
-
Click on the Exchange dependencies button on the left
-
Click the + (plus) icon in the panel
A pop up window will appear reflecting all assets from your organization and MuleSofts´ global exchange which you can reference for your API specification
-
In the drop down please select your Business Group
-
Select your <your initials>-Datatypes fragment
-
Select the Client ID Enforcement trait
-
Click Add 2 dependencies
In order to save some time, please refer to the below RAML snippet
-
Copy the snippet below and amend your worksheet
|
Make sure to paste the snippet below the title property of your worksheet. RAML is indentation sensitive so it is important paste the snippet in a new line with the cursor at the very left. |
mediaType:
- application/json
version: 1
protocols:
- HTTP
- HTTPS
uses:
datatypes: exchange_modules/8af46d8f-62ae-4181-8b19-512878257837/datatypes/1.0.0/datatypes.raml
traits:
secure: !include exchange_modules/8af46d8f-62ae-4181-8b19-512878257837/clientid-enforcement/1.0.0/clientid-enforcement.raml
/accounts:
is: [secure]
get:
responses:
200:
body:
application/json:
type: datatypes.account[]
examples:
ex1: [
{
"id": "0000000001",
"accountName": "Northwind Outfitters",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "60605",
"country": "US",
"city": "Chicago",
"street1": "123 Clark St",
"state": "IL",
"country_ISO2": "US"
}
]
}
},
{
"id": "0000000002",
"accountName": "Wett",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "69190",
"country": "DE",
"city": "Walldorf",
"street1": "Astorstrasse 34",
"state": "08",
"country_ISO2": "DE"
}
]
}
}]
post:
description: Create Account
body:
application/json:
type: datatypes.account[]
examples:
ex1: [
{
"id": "0000000001",
"accountName": "Northwind Outfitters",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "60605",
"country": "US",
"city": "Chicago",
"street1": "123 Clark St",
"state": "IL",
"country_ISO2": "US"
}
]
}
},
{
"id": "0000000002",
"accountName": "Wett",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "69190",
"country": "DE",
"city": "Walldorf",
"street1": "Astorstrasse 34",
"state": "08",
"country_ISO2": "DE"
}
]
}
}]
responses:
200:
body:
application/json:
/{accountName}:
is: [secure]
get:
responses:
200:
body:
application/json:
type: datatypes.account[]
examples:
ex1: [
{
"id": "0000000001",
"accountName": "Northwind Outfitters",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "60605",
"country": "US",
"city": "Chicago",
"street1": "123 Clark St",
"state": "IL",
"country_ISO2": "US"
}
]
}
},
{
"id": "0000000002",
"accountName": "Wett",
"source": "S4Hana",
"addresses": {
"billing": [
{
"zip": "69190",
"country": "DE",
"city": "Walldorf",
"street1": "Astorstrasse 34",
"state": "08",
"country_ISO2": "DE"
}
]
}
}]You will notice an error when you paste the snippet into the editor. This is because the snippet is referring to another datatype library as the one we have set as a dependency.
Let us fix this by deleting the red underlined text for both uses.datatypes and traits.secure. For traits.secure, be sure to keep the !include string.
Navigate to the built on files on the left, and drill down to find your dependencies you just created. Click the elipses and copy the clientid-enforcement.raml path to secure: !include, and copy the datatypes.raml path to datatypes:
On the right side of your worksheet is an API Console where developers can experience the behavior of their API design through interactive documentation that is dynamically generated.
Click on the GET method for the /accounts resource.
Cick on Try It
Fill out the required header values enforced by the Client ID Enforcement trait. These can be any values for testing and then click Send
You will now see an example response from the API
Step 3: Publish the SAP S/4HANA System API Design to Exchange
In order other developers can discover and use your API Design, we will publish the API to the private Anypoint Exchange
Click on Publish at the top right and then click on Publish to Exchange
A new pop up window will appear
-
Fill in a version number eg 1.0.0
-
Click Publish to Exchange
A confirmation window will appear
-
Click on Exchange
You will now be directed to your API in Exchange where we can further document our API Design
Now we can edit the documentation of our API
-
Click on any Edit button as highlighted below
Exchange assets are documented using "markdown" language. Markdown language is a format-agnostic syntax used for creating documentation independent of how it will be rendered (i.e. HTML, PDF, text, etc). It is used by popular applications like GitHub as the standard way to create software documentation. For more information on markdown please refer to:
-
Describe and give your API additional details.
|
You can also paste images into your documentation. e.g. Architecture Reference, etc. |
-
Click on Save
-
Click on Publish
Summary
Congratulations you have finished Module 2 Lab 1. In this lab, you learned about the following:
-
Created a common data types library fragment in APi Designer.
-
Created the API specification for the SAP S/4HANA System API and resued the library fragment as part of the spec.
-
Published the API specification to the private Anypoint Exchange
In the next lab, we’ll take the API specification that we published to Exchange and implment the connection to SAP S/4HANA in Anypoint Studio.