The blog post is part of the series Side-by-Side Extension of SAP Asset Performance Management.
In this blog, we shall walkthrough the steps to be followed for working with GraphQL APIs published by SAP Asset Performance Management (hereinafter referred to as “APM“ for brevity), and few examples to demonstrate the execution of queries and mutations for accessing data that you need from APM GraphQL applications.
By the end of this blog, you will
To know more about consumption of different APIs provided by APM, please refer to blog Extending SAP Asset Performance Management: Consume Standard API
SAP Asset Performance Management entitlement is assigned to a sub-account and already subscribed to it.
What is GraphQL ?
In simple words, GraphQL is a query language for APIs, using which you can efficiently fetch the required data from server. GraphQL provides a complete and understandable description of the data model in your API, and gives users the power to ask for exactly what data they need and nothing more.
Unlike traditional REST APIs, where multiple endpoints are often required to retrieve different data entities, GraphQL allows you to access all data using a single endpoint. The way we call a GraphQL API is very similar to calling any REST or OData API from any HTTP client.
APM APIs are published in SAP Business Accelerator Hub (https://api.sap.com). To explore different APIs that APM has to offer, follow the steps given below.
Also 'API Resources' section allows you to download GraphQL schema file, which is useful for building requests in a Rest Client tool such as Postman or GraphqQL Playground, which is demonstrated later in this blog.
Switch to ”API Reference” tab to explore different Operations and Types provided by application. Left sidebar provides list of Operations and Types available, clicking on which will take you to specific Query, Mutation or Type documentation, as shown in the image below.
Before executing a GraphQL API, let us go through the basics of understanding an API schema in SAP Business Accelerator Hub (APIHub) documentation. Let us look at "recommendations” query as an example, which is used to fetch a list of recommendation objects from server.
2.1 Explore a Query
In Recommendation’s API reference tab, click on “recommendations” query in sidebar to view the query documentation. Documentation contains description, Input arguments, Response type and Schema details as shown in image below.
As shown below, recommendations query accepts few input arguments which are optional in this case (argument name ending with exclamation character indicates the mandatory argument, example- ssid! ). Based on your need, you can optionally pass filter, search, sort, pagination (offset, first) arguments during API request, as listed in Arguments table.
Recommendations query returns a response of type ”RecommendationConnection” type. You can click on “RecommendationConnection” hyperlink to get the details of this type, as shown below.
Since GraphQL requires you to specify the fields that you want to fetch in response, you can further drill down on the edges, pageInfo and totalCount types (highlighed in image below) to identify the fields that you would like to request during API Call.
Query section provides you with precise request and response fields that you can use, as shown in the image below. While calling an API, you need to pass required input arguments, and specify the required response fields, as per the Response schema shown below.
Based on understanding of recommendations query till now, your simple query to “fetch first 10 recommendations” would look like this.
You can see 2 input arguments (first, offset) passed in the example, which will fetch first 10 recommendations from the server.
And in the response, it is fetching multiple fields like id, createdBy, createdOn, description, technicalObjects etc.
If response contains any non-scalar types like “description” and “technicalObjects“ in this example, you need to specify the fields you would like to fetch from these non-scalar types. In the example above, fields short and long are fetched from description type. Similarly fields ssid, objectType and number are fetched from technicalObjects type.
Now that we have a basic understanding of GraphQL API and Schema, lets execute a GraphQL query using Postman.
In Postman, go to APIs tab and click on “+” to create a new API Definition, as shown below
Provide name for newly created API
Click on "create". And select GraphQL as Definition type and JSON as Definition format.
Finally click on ”Create Definition” button.
Copy the content of GraphQL schema file downloaded in section 1.5, and paste into editor as shown below.
Click on Save.
Now API definition for Recommendation is ready !!
Create a new request in Postman. Provide URL and Request headers as shown below.
In request body, select API definition created in section 3.1
Select GraphQL radio button and add Query content in request body, as shown below.
You can build a query in Query editor directly (as shown above) or paste it from some other editor.
Postman provides auto-completion feature while writing query which makes it easier to generate query with suggestions provided as shown below. (CTRL + Space key will trigger the suggestions and you can select the required fields from the suggested list.
Postman also provides query validation feature, which highlights potential errors in the query. In the example below, you can see errors indicated in Red, and hovering over the error pops up a message with more information.
And when you are ready with request, you can execute by hitting Send button. Response contains list of recommendation objects, as shown below.
In previous section, we executed a simple query to fetch list of recommendations. Now let us look at passing an input argument to GraphQL query. In the example below, we will pass a filter to fetch recommendations filtered by a set of technical object numbers.
During API Call, filterInput variable is passed to query as input argument, as pointed in line #1 in the example above.
Further, If you want to combine multiple filter conditions, you can use Join condition as shown below. Here we are defining filters on 2 fields (number and displayId) with AND join condition.
You can also create complex filters using the combination of both allOf and anyOf operators as shown in the example below.
Executing a Mutation is very similar to executing a Query, which we have seen in detail in previous section. Now let us look at a mutation createRecommendation as an example in this section.
Click on RecommendationCreateInput type to see the list of fields allowed in input argument.
Now create a request based on API documentation described above.
In the example below, mutation createRecommendation is called by passing an input argument of type RecommendationCreateInput. Input argument value is defined as JSON object on right side as highlighted. Request body also contains list of fields to be retrieved in response.
After the execution, newly created recommendation details are returned as part of Response, as requested.
GraphQL makes working with a complex, nested data model easier. APM GraphQL APIs are designed considering the nature of strategy objects and their data models.
GraphQL Schema acts as a contract based on which you can build your request. This gives an application developer freedom to build and execute a query to fulfil their application data needs.
To know more about consumption of different APIs provided by APM, please refer to blog Extending SAP Asset Performance Management: Consume Standard API
Stay tuned for further blog posts in the series. Share your feedback or thoughts in the comment section of this blog post.
Furthermore, explore our SAP Asset Performance Management Topic Page and follow the tag SAP Asset Performance Management to not miss out on more content to come!
Side-by-Side Extension of SAP Asset Performance Management: Overview
In this blog, we shall walkthrough the steps to be followed for working with GraphQL APIs published by SAP Asset Performance Management (hereinafter referred to as “APM“ for brevity), and few examples to demonstrate the execution of queries and mutations for accessing data that you need from APM GraphQL applications.
By the end of this blog, you will
- have basic understanding of GraphQL APIs
- be able to explore APM GraphQL APIs documented in SAP Business Accelerator Hub
- be able to execute GraphQL queries in a REST client to fetch data
To know more about consumption of different APIs provided by APM, please refer to blog Extending SAP Asset Performance Management: Consume Standard API
Prerequisites
SAP Asset Performance Management entitlement is assigned to a sub-account and already subscribed to it.
What is GraphQL ?
In simple words, GraphQL is a query language for APIs, using which you can efficiently fetch the required data from server. GraphQL provides a complete and understandable description of the data model in your API, and gives users the power to ask for exactly what data they need and nothing more.
Unlike traditional REST APIs, where multiple endpoints are often required to retrieve different data entities, GraphQL allows you to access all data using a single endpoint. The way we call a GraphQL API is very similar to calling any REST or OData API from any HTTP client.
In order to work with GraphQL APIs, we need to understand 3 basic things, ie. Queries, Mutations and Types.
- Type
A Type in GraphQL represents a kind of object that you can fetch from an API. Type provides information about the fields it contains.In the example below, a type called Character is defined with 3 fields, ie. name of the character, movie that character appears in and rating for the character.
type Character {
name: String!
movie: String!
rating: Int
}
While querying data for type Character, you need to specify the fields that you want to fetch from server.
- QueryA Query is used to fetch data, which is similar to GET operation in REST APIs. GraphQL allows you to define precisely what data you want to fetch from server. In the example below, getCharacters query is used to fetch Character data. This query is fetching only 2 fields, ie. name and movie.
query getCharacters {
Character {
name
movie
}
}
- Mutation
A Mutation is used to create, modify or delete data in API. In the example below, createCharacter mutation is used to create a Character by passing input arguments. You can also notice fields (name and movie) requested as part of response.
mutation {
createCharacter ( name: “Hulk”, movie: “Avengers”, rating: 😎
{
name
movie
}
}
You can learn more about GraphQL Types, Queries and Mutations here.
1. Explore APM GraphQL APIs
APM APIs are published in SAP Business Accelerator Hub (https://api.sap.com). To explore different APIs that APM has to offer, follow the steps given below.
1.1 Go to https://api.sap.com in web browser of your preference
1.2 Search for keyword “APM” in search box
1.3 Find GraphQL Applications
1.4 Select ”GraphQL API” tab to find all GraphQL applications
1.5 Explore overview of APIs
Also 'API Resources' section allows you to download GraphQL schema file, which is useful for building requests in a Rest Client tool such as Postman or GraphqQL Playground, which is demonstrated later in this blog.
1.6 Explore API reference
Switch to ”API Reference” tab to explore different Operations and Types provided by application. Left sidebar provides list of Operations and Types available, clicking on which will take you to specific Query, Mutation or Type documentation, as shown in the image below.
2. Understand a GraphQL API
Before executing a GraphQL API, let us go through the basics of understanding an API schema in SAP Business Accelerator Hub (APIHub) documentation. Let us look at "recommendations” query as an example, which is used to fetch a list of recommendation objects from server.
2.1 Explore a Query
In Recommendation’s API reference tab, click on “recommendations” query in sidebar to view the query documentation. Documentation contains description, Input arguments, Response type and Schema details as shown in image below.
As shown below, recommendations query accepts few input arguments which are optional in this case (argument name ending with exclamation character indicates the mandatory argument, example- ssid! ). Based on your need, you can optionally pass filter, search, sort, pagination (offset, first) arguments during API request, as listed in Arguments table.
Recommendations query returns a response of type ”RecommendationConnection” type. You can click on “RecommendationConnection” hyperlink to get the details of this type, as shown below.
Since GraphQL requires you to specify the fields that you want to fetch in response, you can further drill down on the edges, pageInfo and totalCount types (highlighed in image below) to identify the fields that you would like to request during API Call.
2.2 Query Schema section
Query section provides you with precise request and response fields that you can use, as shown in the image below. While calling an API, you need to pass required input arguments, and specify the required response fields, as per the Response schema shown below.
2.3 Example Query
Based on understanding of recommendations query till now, your simple query to “fetch first 10 recommendations” would look like this.
You can see 2 input arguments (first, offset) passed in the example, which will fetch first 10 recommendations from the server.
And in the response, it is fetching multiple fields like id, createdBy, createdOn, description, technicalObjects etc.
If response contains any non-scalar types like “description” and “technicalObjects“ in this example, you need to specify the fields you would like to fetch from these non-scalar types. In the example above, fields short and long are fetched from description type. Similarly fields ssid, objectType and number are fetched from technicalObjects type.
3. Calling a GraphQL API
Now that we have a basic understanding of GraphQL API and Schema, lets execute a GraphQL query using Postman.
3.1 Import Schema Definition
In Postman, go to APIs tab and click on “+” to create a new API Definition, as shown below
Provide name for newly created API
Click on "create". And select GraphQL as Definition type and JSON as Definition format.
Finally click on ”Create Definition” button.
Copy the content of GraphQL schema file downloaded in section 1.5, and paste into editor as shown below.
Click on Save.
Now API definition for Recommendation is ready !!
3.2 Create a request
Create a new request in Postman. Provide URL and Request headers as shown below.
In request body, select API definition created in section 3.1
Select GraphQL radio button and add Query content in request body, as shown below.
You can build a query in Query editor directly (as shown above) or paste it from some other editor.
Postman provides auto-completion feature while writing query which makes it easier to generate query with suggestions provided as shown below. (CTRL + Space key will trigger the suggestions and you can select the required fields from the suggested list.
Postman also provides query validation feature, which highlights potential errors in the query. In the example below, you can see errors indicated in Red, and hovering over the error pops up a message with more information.
And when you are ready with request, you can execute by hitting Send button. Response contains list of recommendation objects, as shown below.
3.3 Passing parameters to a request
In previous section, we executed a simple query to fetch list of recommendations. Now let us look at passing an input argument to GraphQL query. In the example below, we will pass a filter to fetch recommendations filtered by a set of technical object numbers.
During API Call, filterInput variable is passed to query as input argument, as pointed in line #1 in the example above.
Further, If you want to combine multiple filter conditions, you can use Join condition as shown below. Here we are defining filters on 2 fields (number and displayId) with AND join condition.
You can also create complex filters using the combination of both allOf and anyOf operators as shown in the example below.
3.4 Executing a Mutation
Executing a Mutation is very similar to executing a Query, which we have seen in detail in previous section. Now let us look at a mutation createRecommendation as an example in this section.
Click on RecommendationCreateInput type to see the list of fields allowed in input argument.
Now create a request based on API documentation described above.
In the example below, mutation createRecommendation is called by passing an input argument of type RecommendationCreateInput. Input argument value is defined as JSON object on right side as highlighted. Request body also contains list of fields to be retrieved in response.
After the execution, newly created recommendation details are returned as part of Response, as requested.
Conclusion
GraphQL makes working with a complex, nested data model easier. APM GraphQL APIs are designed considering the nature of strategy objects and their data models.
GraphQL Schema acts as a contract based on which you can build your request. This gives an application developer freedom to build and execute a query to fulfil their application data needs.
To know more about consumption of different APIs provided by APM, please refer to blog Extending SAP Asset Performance Management: Consume Standard API
Stay tuned for further blog posts in the series. Share your feedback or thoughts in the comment section of this blog post.
Furthermore, explore our SAP Asset Performance Management Topic Page and follow the tag SAP Asset Performance Management to not miss out on more content to come!
Related Content
Side-by-Side Extension of SAP Asset Performance Management: Overview
- SAP Managed Tags:
| User | Count |
|---|---|
| 8 | |
| 7 | |
| 6 | |
| 4 | |
| 4 | |
| 4 | |
| 3 | |
| 3 | |
| 3 | |
| 3 |
