Hello!
In this part of the tutorial on Graph we will focus on the support of REST services in Graph. For an overview of other parts of this series, check out the Information Map.
REST support in Graph
Graph enables the use of REST services as data sources for business data graphs (BDGs). Compared to OData data sources, there are some key differences:
The metadata that describes the service must be provided separately along with the service endpoint in the OpenAPI format.OpenAPI does not have the concept of entities like OData does. Instead, it focuses on operations, which are represented as actions and functions in a BDG.
We will now explain how these differences are being handled by Graph in more detail:
Metadata for a REST service
REST services are commonly described using the OpenAPI format, which outlines the operations and resources available in the service. Unlike OData, which provides a $metadata endpoint for accessing service metadata, plain REST services do not have a standard way to access this information. Since Graph requires metadata to work with REST services, users must provide this metadata when setting up a business data graph.
Graph uses BTP destinations to define access to data sources. To use a REST service as data source, users need to create 2 destinations:
a data destination: that points to the actual REST servicea metadata destination: where the OpenAPI metadata document for the REST service can be retrieved
Both destinations also need annotations that connect them together, so that Graph can understand which metadata destination belongs to which REST service destination.
Data Model
Graph exposes a unified API endpoint for the OData and GraphQL protocols. Both offer an entity (or type/object) model in which data can be represented. Plain REST as described by OpenAPI does not have a strict entity model, and services are defined as different operations. For example, an operation might be to ‘find a pet by name’ or ‘retrieve pets of a store’ in a pet-store service. However, to expose these REST-operations as valid OData in the unified API, Graph transforms them into unbound OData operations (actions & functions) in the BDG. We refer to these also as mirrored operations, similar to mirrored entities. As part of that transformation, some changes are made to the signature of the operations to align with the OData standard. These include:
all paths are flattened: for example a GET /users/pets is transformed to a GET users_pets in the BDGall methods are standardized to GET and POST, with the underlying method being appended to the operation name: for example a DELETE /users/pets becomes a POST /users_pets__delete
Example
Having explained the main concepts of REST support in Graph, let’s now look at a practical example. We will take the try-out sandbox of this SAP Ariba Network Catalog Management REST service and use it in a BDG. You can also download the OpenAPI metadata document for the service there under API Resources / API specification.
Tutorial Setup
Before we can use the SAP Ariba service in a BDG, we need to setup the two destinations in SAP BTP.
Prerequisites:
SAP Integration Suite with API Management and Graph enabledAccess to destinations and service instances in SAP BTP cockpit
Data Destination
Open the SAP BTP Cockpit and create a new destination from scratch in the BTP subaccount where you have Graph and SAP Integration Suite. Enter the following details
Name: ariba-network-catalog-mgmtURL: https://sandbox.api.sap.com/ariba/api/network-catalog-mgmt/v1/sandbox
Also add these two additional properties to the destination:
Key: Graph.destinationType with the value: REST. This declares this destination as a REST data destination to Graph.Key: URL.headers.apiKey with the value: <your sandbox API key> to add your sandbox API key for authentication purposes (this only applies to this sandbox-example). You can retrieve your API key here: https://api.sap.com/settings.
data destination in BTP cockpit
Metadata Destination
Next, we need to define the metadata destination that points to a location where Graph can access the OpenAPI metadata document. This could be done in a number of ways by hosting this file in a file-server/document storage or at a custom service endpoint for example. For sake of keeping this tutorial simple we will only use SAP Integration Suite to make this file available to Graph: we will create an API artifact which returns the content of the OpenAPI metadata file and then create the metadata destination that points towards the endpoint of that API artifact. Note that this is only for the purposes of this tutorial, and not a requirement.
Hosting the OpenAPI file with an API artifact (optional, only for the tutorial)
First we create the API artifact in SAP Integration Suite. Open Integration Suite and go to Design > Integrations and APIs. Choose an existing package or create a new one. In the package click Edit and open the Artifacts tab. Now you can select Add > API in the table menu. Follow the API creation dialog and select REST API as API Type, Create as Method and then give it the following name: Ariba-Network-Catalog-OpenAPI. Open the created API and in the ‘Handle Request’ lane select the ‘Content Modifier’ step. In the bottom UI panel you will then see the Message Body tab where we can paste a constant body this API should return. Here, we will paste the JSON content of the OpenAPI specification of the service (available here). If you have other APIs in the tenant you might also want to assign a unique path for this API. To do that select the HTTPS arrow outgoing from the Start participant, and then in the bottom UI panel you can edit the ‘Connection’ and change the path in the ‘Address’ field. Here, we are using /ariba-network-catalog-openapi. Then save the API artifact and deploy it. You can check the deployment status under Monitor > Integrations and APIs > Manage Integration Content: All. When it is deployed, the OpenAPI document will be available at that endpoint. Copy the endpoint URL for later.
constant message body returns the OPenAPI spec JSON
unique path for this API artifact
monitoring view of the deployed API artifact, with the endpoint URL
To access that endpoint in a destination, we also need the authentication details. Here, we want to authenticate using OAuth client credentials that we obtain from a SAP Process Integration Runtime. For that, go to BTP Cockpit and under Services > Instances and Subscriptions you can find it or create a new one. Then create a Service Key for that instance. We now have a set of client credentials we need for authentication: namely the clientid, clientsecret and tokenurl.
process integration runtime with a service key in BTP cockpit
Creating the Destination
Now we can create the Metadata destination. Enter the following details:
Name: ariba-network-catalog-mgmt-openapiURL: the API artifact endpoint URL from aboveAuthentication: OAuth2ClientCredentialsClient ID: clientid from aboveClient Secret: clientsecret from aboveToken Service URL: tokenurl from above
We will also annotate this destination with additional properties, to tell Graph that this is the metadata destination for the previously created ariba-network-catalog-mgmt destination:
Key: Graph.destinationType, with a value of OpenAPIKey: Graph.metadataFor, with a value of ariba-network-catalog-mgmt
metadata destination
Now the destination setup is complete and we can create a BDG.
Creating the BDG with REST data sources
With the data destination and the metadata destination created, we can now continue to create a BDG with the REST service. The process does not differ much in this case. In Integration Suite under Design > Graph, create a new Business Data Graph with the ID rest-bdg. In the list of destinations, you can now see an ariba-network-catalog-mgmt entry with the type REST. The info icon shows you more details, for example that Graph has identified which metadata destination belongs to this entry. Just select the entry and continue. When the dialog is finished and we see a preview of the BDG details, we can also change the namespace of the data source from my.custom to my.ariba (this is optional). Continue by activating the BDG.
data source selection when creating a new BDG
editing the namespace of a data source
overview of the activated BDG
Making Queries against the BDG
With the BDG activated, we can now inspect the mirrored operations. Open the BDG in Developer Hub (there is a link on the overview tab of the BDG). You will see the following operations:
GET products (mirrored from GET /products)GET products_ (mirrored from GET /products/{productid})POST products__delete (mirrored from DELETE /products/{productid})POST products__patch (mirrored from PATCH /products/{productid})POST products_post (mirrored from POST /products)
The productid path parameter here is either transformed into an unbound function path parameter, or an unbound action body parameter in this example. This illustrates the transformation that Graph makes of the mirrored operations into valid OData operations as mentioned earlier. In the try out tab we can see all the parameters of the operation and also give it a go.
Note: Graph treats all parameters of mirrored operations as required at this time. However, you can set the value to null.
Summary
In this tutorial we had a look at how REST services can be used as data sources in a business data graph. With this feature, you can integrate data from REST services alongside data from OData services into a single unified Graph API.
You can learn more about REST-support in Graph in the documentation:
REST services as data sourcesConnect to your business systems: REST services
—
Florian Moritz
Hello!In this part of the tutorial on Graph we will focus on the support of REST services in Graph. For an overview of other parts of this series, check out the Information Map.REST support in GraphGraph enables the use of REST services as data sources for business data graphs (BDGs). Compared to OData data sources, there are some key differences:The metadata that describes the service must be provided separately along with the service endpoint in the OpenAPI format.OpenAPI does not have the concept of entities like OData does. Instead, it focuses on operations, which are represented as actions and functions in a BDG.We will now explain how these differences are being handled by Graph in more detail:Metadata for a REST serviceREST services are commonly described using the OpenAPI format, which outlines the operations and resources available in the service. Unlike OData, which provides a $metadata endpoint for accessing service metadata, plain REST services do not have a standard way to access this information. Since Graph requires metadata to work with REST services, users must provide this metadata when setting up a business data graph.Graph uses BTP destinations to define access to data sources. To use a REST service as data source, users need to create 2 destinations:a data destination: that points to the actual REST servicea metadata destination: where the OpenAPI metadata document for the REST service can be retrievedBoth destinations also need annotations that connect them together, so that Graph can understand which metadata destination belongs to which REST service destination.Data ModelGraph exposes a unified API endpoint for the OData and GraphQL protocols. Both offer an entity (or type/object) model in which data can be represented. Plain REST as described by OpenAPI does not have a strict entity model, and services are defined as different operations. For example, an operation might be to ‘find a pet by name’ or ‘retrieve pets of a store’ in a pet-store service. However, to expose these REST-operations as valid OData in the unified API, Graph transforms them into unbound OData operations (actions & functions) in the BDG. We refer to these also as mirrored operations, similar to mirrored entities. As part of that transformation, some changes are made to the signature of the operations to align with the OData standard. These include:all paths are flattened: for example a GET /users/pets is transformed to a GET users_pets in the BDGall methods are standardized to GET and POST, with the underlying method being appended to the operation name: for example a DELETE /users/pets becomes a POST /users_pets__deleteExampleHaving explained the main concepts of REST support in Graph, let’s now look at a practical example. We will take the try-out sandbox of this SAP Ariba Network Catalog Management REST service and use it in a BDG. You can also download the OpenAPI metadata document for the service there under API Resources / API specification.Tutorial SetupBefore we can use the SAP Ariba service in a BDG, we need to setup the two destinations in SAP BTP.Prerequisites:SAP Integration Suite with API Management and Graph enabledAccess to destinations and service instances in SAP BTP cockpitData DestinationOpen the SAP BTP Cockpit and create a new destination from scratch in the BTP subaccount where you have Graph and SAP Integration Suite. Enter the following detailsName: ariba-network-catalog-mgmtURL: https://sandbox.api.sap.com/ariba/api/network-catalog-mgmt/v1/sandboxAlso add these two additional properties to the destination:Key: Graph.destinationType with the value: REST. This declares this destination as a REST data destination to Graph.Key: URL.headers.apiKey with the value: <your sandbox API key> to add your sandbox API key for authentication purposes (this only applies to this sandbox-example). You can retrieve your API key here: https://api.sap.com/settings.data destination in BTP cockpitMetadata DestinationNext, we need to define the metadata destination that points to a location where Graph can access the OpenAPI metadata document. This could be done in a number of ways by hosting this file in a file-server/document storage or at a custom service endpoint for example. For sake of keeping this tutorial simple we will only use SAP Integration Suite to make this file available to Graph: we will create an API artifact which returns the content of the OpenAPI metadata file and then create the metadata destination that points towards the endpoint of that API artifact. Note that this is only for the purposes of this tutorial, and not a requirement.Hosting the OpenAPI file with an API artifact (optional, only for the tutorial)First we create the API artifact in SAP Integration Suite. Open Integration Suite and go to Design > Integrations and APIs. Choose an existing package or create a new one. In the package click Edit and open the Artifacts tab. Now you can select Add > API in the table menu. Follow the API creation dialog and select REST API as API Type, Create as Method and then give it the following name: Ariba-Network-Catalog-OpenAPI. Open the created API and in the ‘Handle Request’ lane select the ‘Content Modifier’ step. In the bottom UI panel you will then see the Message Body tab where we can paste a constant body this API should return. Here, we will paste the JSON content of the OpenAPI specification of the service (available here). If you have other APIs in the tenant you might also want to assign a unique path for this API. To do that select the HTTPS arrow outgoing from the Start participant, and then in the bottom UI panel you can edit the ‘Connection’ and change the path in the ‘Address’ field. Here, we are using /ariba-network-catalog-openapi. Then save the API artifact and deploy it. You can check the deployment status under Monitor > Integrations and APIs > Manage Integration Content: All. When it is deployed, the OpenAPI document will be available at that endpoint. Copy the endpoint URL for later.constant message body returns the OPenAPI spec JSON unique path for this API artifact monitoring view of the deployed API artifact, with the endpoint URLTo access that endpoint in a destination, we also need the authentication details. Here, we want to authenticate using OAuth client credentials that we obtain from a SAP Process Integration Runtime. For that, go to BTP Cockpit and under Services > Instances and Subscriptions you can find it or create a new one. Then create a Service Key for that instance. We now have a set of client credentials we need for authentication: namely the clientid, clientsecret and tokenurl.process integration runtime with a service key in BTP cockpit Creating the DestinationNow we can create the Metadata destination. Enter the following details:Name: ariba-network-catalog-mgmt-openapiURL: the API artifact endpoint URL from aboveAuthentication: OAuth2ClientCredentialsClient ID: clientid from aboveClient Secret: clientsecret from aboveToken Service URL: tokenurl from aboveWe will also annotate this destination with additional properties, to tell Graph that this is the metadata destination for the previously created ariba-network-catalog-mgmt destination:Key: Graph.destinationType, with a value of OpenAPIKey: Graph.metadataFor, with a value of ariba-network-catalog-mgmtmetadata destinationNow the destination setup is complete and we can create a BDG.Creating the BDG with REST data sourcesWith the data destination and the metadata destination created, we can now continue to create a BDG with the REST service. The process does not differ much in this case. In Integration Suite under Design > Graph, create a new Business Data Graph with the ID rest-bdg. In the list of destinations, you can now see an ariba-network-catalog-mgmt entry with the type REST. The info icon shows you more details, for example that Graph has identified which metadata destination belongs to this entry. Just select the entry and continue. When the dialog is finished and we see a preview of the BDG details, we can also change the namespace of the data source from my.custom to my.ariba (this is optional). Continue by activating the BDG.data source selection when creating a new BDG editing the namespace of a data source overview of the activated BDGMaking Queries against the BDGWith the BDG activated, we can now inspect the mirrored operations. Open the BDG in Developer Hub (there is a link on the overview tab of the BDG). You will see the following operations:GET products (mirrored from GET /products)GET products_ (mirrored from GET /products/{productid})POST products__delete (mirrored from DELETE /products/{productid})POST products__patch (mirrored from PATCH /products/{productid})POST products_post (mirrored from POST /products)The productid path parameter here is either transformed into an unbound function path parameter, or an unbound action body parameter in this example. This illustrates the transformation that Graph makes of the mirrored operations into valid OData operations as mentioned earlier. In the try out tab we can see all the parameters of the operation and also give it a go.Note: Graph treats all parameters of mirrored operations as required at this time. However, you can set the value to null. This SAP Ariba sandbox API requires an X_ARIBA_NETWORK_ID parameter. You can use the value AN02005777309 for this sandbox. When running the my.ariba/products operation, we can see that we get the response from the REST service in a valid OData format. trying out the mirrored functions in Developer Hub (Graph Navigator)SummaryIn this tutorial we had a look at how REST services can be used as data sources in a business data graph. With this feature, you can integrate data from REST services alongside data from OData services into a single unified Graph API.You can learn more about REST-support in Graph in the documentation:REST services as data sourcesConnect to your business systems: REST services–Florian Moritz Read More Technology Blog Posts by SAP articles
#SAP
#SAPTechnologyblog
