Consuming GraphQL APIs
A quick recap of GraphQL APIs
GraphQL is a query language for APIs which allows the client to determine the structure of the required data. The client always sends the structured query with HTTP POST to a certain endpoint and the server returns JSON data according to the query. This gives the client more freedom and power over the usage but in return requires more knowledge and responsibility of the endpoint usage.
How to consume GraphQL APIs
As GraphQL APIs return JSON data, it is suggested to utilize the RestRequest Task for the benefit of automatically deserialized body for easier reference later on the Process.
Consuming GraphQL APIs differ from REST API consumption in four details:
The server endpoint or URI remains always the same with GraphQL
HTTP method is always POST
The request payload contains the GraphQL query
Depending on the query format, the Content-Type HTTP header varies
Let's go through an example of consuming a GraphQL API with those four details.
Our example is consuming the GraphQL API of Helsinki Regional Transport Authority to get directions between two coordinates using methods of public transport. Also, GraphQL API service providers sometimes provide an UI for exploring and testing the GraphQL API itself and one of these tools is called GraphiQL. In this case we can use GraphiQL for the same API for testing purposes and figuring out how the query would work.
The endpoint to be used is https://api.digitransit.fi/routing/v1/routers/hsl/index/graphql and from the GraphiQL tool we can determine our payload like in the image below.
We can copy paste that payload to RestRequest Task Message field and set HTTP Header Content-Type: application/graphql.
Now we have all our needed parameters for the RestRequest Task which would look like the following:
And of course, depending on the use case, we could reference for instance the coordinates from variables or previous Task results for dynamic solution.
One option to represent a GraphQL query in the HTTP request payload is to use a JSON with property query and its string value as the GraphQL query. Note that now the HTTP headers must be Content-Type: application/json .and the string must be presented as oneliner with possible escapes. For the same query as above, this would look like following:
Exception handling with GraphQL APIs
The exception handling of GraphQL APIs should rely on the same practices as with REST APIs or SOAP services because the functionality from HTTP request perspective is the same.
Recap on how to consume GraphQL APIs with Frends
Use RestRequest Task
The endpoint remains always the same as does the method as POST
The payload can be formatted as GraphQL query or as JSON with the GraphQL query as query property's value
Handle exceptions like any other HTTP integration use case
The next article is Introduction to Other techniques for HTTP requests