Go GraphQL with AWS Appsync & SAP PO

[Sebastian76]

Overview

GraphQL is an emerging API definition standard that originated from Facebook engineering.

The GraphQL approach of defining an API includes a data fetching/manipulation language with self describing format of data organized in a "graph" like manor (More details on https://graphql.org/)

The adoption of GraphQL has been growing over the years (examples are the public or partnered APIs of Paypal, Braintree, Fluent OMS or LeanIX).

AWS supports building custom GraphQL APIs through AWS Appsync service.

This blog shows how to invoke such GraphQL resources in AWS Appsync with SAP PO and KaTe AWS Adapter.

Define a Appsync GraphQL endpoint

AWS Appsync exposes APIs as serverless GraphQL Proxy in front of services like DynamoDB, AuroraDB or ElasticSearch "out of the box".

For more custom data sources also Http endpoints or Lambda functions can be used as shown in the picture below.

Source: https://aws.amazon.com/de/appsync/

Order example

For an imaginary example use case let's create a simple GraphQL service which could CRUD (create/read/update/delete) a order object in a DynamoDB table.

AWS Appsync allows you to build such a service in top down (define schema first) or bottom up fashion (define DynamoDB table first).

We'll use top down approach for this example. In order to do so we create a API definition via the Appsync console:

https://console.aws.amazon.com/appsync/home=> Create API



Source: https://aws.amazon.com/de/appsync/

The next step is to define an order object and its fields with datatypes.

GraphQL defines a fixed set of predefined datatypes that can be extended by custom datatypes (e.g. AWS Appsync has a few of them like ISO-compatible DateTime or Date).

Source: https://aws.amazon.com/de/appsync/

Saving this will create a GraphQL schema for querying and mutation of the underlying object as well as a DynamoDB Table to persist the object.

The GraphQL schema contains a simple definition of an order that can be accessed as CRUD operations (or in GraphQL terms queries and mutations):

• createOrder


• updateOrder


• deleteOrder


• listOrders


• getOrder

Below is a ( shortened) representation of the created GraphQL schema displayed on the Schema tab of the AWS GraphQL console:

input CreateOrderInput {

	product: String

	amount: Int

	orderDate: AWSDateTime

}



input DeleteOrderInput {

	id: ID!

}



type Mutation {

	createOrder(input: CreateOrderInput!): Order

	updateOrder(input: UpdateOrderInput!): Order

	deleteOrder(input: DeleteOrderInput!): Order

}



type Order {

	id: ID!

	product: String

	amount: Int

	orderDate: AWSDateTime

}



type OrderConnection {

	items: [Order]

	nextToken: String

}



type Query {

	getOrder(id: ID!): Order

	listOrders(filter: TableOrderFilterInput, limit: Int, nextToken: String): OrderConnection

}

 

Query and Mutate an order

Inside the AWS Appsync console all different object operations can now be tested via a "What you see is what you get" type of API console:

Source: https://aws.amazon.com/de/appsync/

The GraphQL service is now ready to be used!

Invoking GraphQL from SAP PO

In order to invoke such a service from SAP PO, we'll now use the KaTe AWS adapter with a receiver channel configured for AWS Appsync.

Configuring the receiver channel

First we need to get the settings of our Appsync GraphQL endpoint.

The endpoint and API key can be retrieved from the Settings page of Appsync service



Source: https://aws.amazon.com/de/appsync/

The receiver channel in SAP PO is then configured with this information and the schema obtained from the Schema tab in Appsync as below:



For authentication we use the here AWS API key, but also IAM sigv4 authentication,or any custom API key are supported.

Generating the WSDL schema

As SAP PO's toolset internally uses XML schema based data structures, the adapter works based on a XML schema representation of the GraphQL schema.

Therefore in order to build a scenario we would first generate a WSDL from the GraphQL schema and import it into our ESR.

From there we can build any possible query/mutation operation as XML request/response within SAP PO's "natural" toolset like graphical mappings without any custom coding.

In order to generate the WSDL we first navigate to the adapter UI and choose "Appsync GraphQL schema generator".



 

 

 

 

 

 

 

 

The view allows us to paste the GraphQL schema along some more information like  interface name/namespace for the generated Service interface.

The WSDL can then be imported via the Import Service Interface option of the ESR (or NWDS)



 

 

 

 

 

 

The imported schema represents all the necessary fields to operate on the defined operations of the GraphQL schema that could be easily used from there.

The XML request contains all possible argument fields (here product, amount and orderDate) and the ouput fields:

From there you would build your scenario with the PO developer toolset.

Testing queries

One handy way to explore/test the way the adapter constructs GraphQL queries from the XML structure is also builtin the adpater UI with the option "Appsync GraphQL channel tester".



 

 

 

 

 

 

 

 

The channel tester as a "shortcut" can directly execute calls through a configured receiver channel without a completely configured scenario in PO.

You could choose a channel and the channel tester displays all possible operations for the GraphQL endpoint (derived from the configured GraphQL schema).

By selecting an operation the UI generates a XML sample request (bit similar to SOAPUI) that can be used as basis for a test.

e.g. here we selected our previously configured channel and chose the "mutation_createOrder" operation:

 

Now let's create an Order via the mutation_createOrder operation

We just modify the generated sample request with more meaningful values as argument input object and set the output field returned to just contain the id:

<aws:mutation_createOrder xmlns:aws="http://kate-group.com/adapters/AWS">

  <arguments>

    <input>

      <!--Optional:-->

      <product>shampoo</product>

      <!--Optional:-->

      <amount>1</amount>

      <!--Optional:-->

      <orderDate>2020-12-12T00:00:00Z</orderDate>

    </input>

  </arguments>

  <output>

    <!--Optional:-->

    <id/>

  </output>

</aws:mutation_createOrder>

By hitting "Try it" the call is posted through your receiver channel as it would be at runtime from SAP PO's messaging system.

The UI will display its XML response on the right side ("XML response") along the GraphQL request/response as "on the wire" in the lower left/right text area

 

Let's have a close look at the XML first,

<input>

      <product>shampoo</product>

      <amount>1</amount>

      <orderDate>2020-12-12T00:00:00Z</orderDate>

</input>

As output we want to receive the generated id from our service:

<output>

    <id/>

</output>

The XML is translated into the GraphQL query in json format and send over the wire and is shown in the lower left textarea of the test

mutation createOrder{

  createOrder(

    input:{

       product: "shampoo",

       amount: 1,

       orderDate: "2020-12-12T00:00:00Z"

    }

  )

  {id}

}

The GraphQL response:

{

	"data": {

		"createOrder": {

			"id": "ebae2e66-b066-4988-8228-10e040720ddd"

		}

	}

}

is then translated back into the XML response

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<aws:mutation_createOrder_Response xmlns:aws="http://kate-group.com/adapters/AWS">

  <data>

    <createOrder>

      <id>ebae2e66-b066-4988-8228-10e040720ddd</id>

    </createOrder>

  </data>

</aws:mutation_createOrder_Response>

Summary

The adapter allows you to connect Appsync GraphQL service endpoints as well as any other GraphQL service (e.g. MongoDBRealm on AWS).

Typical authentication mechanisms like AWS Sigv4, AWS api keys or custom other http request based api keys are supported as well as all AWS extended GraphQL datatypes (e.g. AWSDateTime, AWSDate, etc).

By this approach PO developers don't need to build a heap of Java code to achieve connectivity to a GraphQL service but simply focus on building the specific integration needed.

 

https://graphql.org/

KaTe AWS Adapter SAP Appcenter