¶ Querying with GraphQL
GraphQL is a query language for API developed by Facebook and recently adopted by many other services. Basically it should allow you to query just the required data from the API – and have full control over the response JSON.
- Basic information about queries and mutations: https://graphql.org/learn/queries/
- How to work with GraphQL in Postman: https://www.postman.com/postman/workspace/postman-team-collections/documentation/1559645-c0dd3eb3-5258-4ddd-a6e4-2780c5212e33
- How to import GraphQL API schema to Postman: https://learning.postman.com/docs/sending-requests/supported-api-frameworks/graphql/
¶ Request in Postman
Let's have an example of a simple GraphQL query in Postman:
- All queries to GraphQL API are sent as POST and they all point to the same URL.
- You can switch the body type to GraphQL for easier work – and if you imported the API schema to Postman, you can select the right API here (this enables suggestions).
- This is GraphQL query – this example is getting data of a single Wiki page. Note, that you can directly specify, which fields are you requiring in the response.
- If there are some variables in the query (
$pageId:Int) you can set their value in Variables window. - Response is a simple JSON, where all data are packed in the
datanode and the structure is always defined by the query structure.
So how to send this query with RESTwithUS? Well, before we go there, let's have a quick look under the hood and see, what really happens during this GraphQL request:
This is the same request sent to the GraphQL API, but this time we are sending it as a raw JSON. Notice the request structure:
- Entire GraphQL query is "packed" as a string in
querynode. Please note that for this to work you need to delete all line breaks in the query. - Variables JSON is sent in
variablesnode.
¶ Request in RESTwithUS
Now that we know how to send the GraphQL query as a simple JSON request, we can do the same in RESTwithUS.
First create an API provider (and set up authentication if needed):
Then create new POST operation and point it to the GraphQL endpoint (e.g. if you have multiple GraphQL operations, they will all have same Endpoint):
Open the operation Request Body, use function Payload / Import Payload and paste an example of the JSON request there:
This will prepare an empty schema for you:
Let's now make two simple changes:
- Use function Payload / Import Line Value on the
querynode and paste the GraphQL query there. Don't forget to remove all line breaks before pasting the query!
- You will fill the page ID parameter with code, so place a variable
{{pageId}}into thepageIdnode.
Now open the operation Response Body and use function Payload / Import Payload to import the response JSON schema:
We will leave it blank for now but you can map it to Business Central tables and fields if needed.
¶ Run the Operation
Let's test the operation and get a Wiki page with id 1:
var
APIScriptRWU: Codeunit "API Script RWU";
APIScriptRWU.INIT('WIKI_GRAPHQL_GET_PAGE'); //Init the operation and set Batch Code
APIScriptRWU.ENDPOINT('Wiki GraphQL','Get Page'); //Select the provider and operation
APIScriptRWU.ADD_VARIABLE('/variables/pageId','pageId',1); //Assign the page ID to the {{pageId}} variable
APIScriptRWU.EXECUTE(); //Start the operation
Tip: For more API Script functions see guideline API Script Functions Reference.