GraphQL is a data query language and specification developed internally by Facebook in 2012 before being publicly open sourced in 2015. It provides an alternative to REST-based architectures with the purpose of increasing developer productivity and minimizing amounts of data transferred.
How Does GraphQL Compare to REST?
In many respects, GraphQL and REST share the same concepts: data is requested, submitted, and returned between systems over HTTPS. The transferred data is in a structured format such as JSON.
But the biggest different between the two architectures lies in how data is requested and returned. Think of REST like a fixed-course menu. You only get what the chef has pre-determined will be served; no substitutions allowed. GraphQL, on the other hand, is like an a la carte menu. You get to choose which elements you want and the order in which they appear in the response payload.
The advantage therefore of GraphQL over REST is that you can extract data in a single method call which otherwise would take five or six separate REST calls.
Using GraphQL in Maropost for Marketing
As of the moment, we are using GraphQL as an alternative to REST for retrieving data from your Maropost for Marketing account. If you wish to submit and modify data via our APIs, then you must continue using our REST API for that activity.
The GraphQL Online API guide lists the various queries that are available for you to construct. You'll find the guide on the Connections page. To navigate to the page, mouse over your user name in the top right corner of the menu bar and select "Connections" from the selection list. On the Connections page, click the GraphQL API tab.
The online guide shows you the different GraphQL services that are currently supported. We will continue to add more services in future releases.
Click the tab of each service to see the full menu of data points that are available to retrieve. In your actual call, your request payload will only include those elements and attributes that you wish to retrieve. GraphQL is an entirely self-defined data structure. By "self-defined", this term means that you determine which elements and attributes you want to retrieve, and how they appear in sequence within the response payload.
Pulling Data Using the GraphQL API Endpoint
The API endpoint for our GraphQL service is https://api.maropost.com/accounts/:account_id/graphql. You will still issue a POST command, even though you are retrieving data, not submitting it. Also remember to include an API auth_token as a query string parameter in the URL.
The response data is still returned in virtual "pages," just like it is returned by the REST API. We recommend that you include the "total_pages" attribute in each of your method calls. By knowing how many records are included in each virtual page, and the total number pages, you can programmatically retrieve the full result set of data.
Each GraphQL API method returns a default number of records per page. (For example, the Campaigns API returns 3 campaigns per page by default.) You can change the number of records per page using the per parameter. Hence by including per: 50 as a parameter in the request for Campaign data, you can increase the number to 50 campaigns per virtual page.
With the Campaigns API, you can use a single method call to retrieve summary data for campaigns (total sends, total unique opens, total unique clicks, etc.) together with information about each individual contact who was sent the campaign.
By default, the Campaigns API returns information for all campaign types. You can include the type parameter if you want to only select specific types of campaigns, e.g. only Journey campaigns, or only A|B Test campaigns.
The Contacts API gives you access to the entire history of your contacts including their profile attributes, which lists they have subscribed to, what Journeys they have been in, what orders they have placed, and what campaigns they have responded to.
Product and Revenue API
This API method gives you access to the data stored in your Product and Revenue database. As mentioned previously, Maropost's GraphQL API is used only for retrieving data out of your account's database. You'll still need to use either the REST API or the web tracking script to add data to your Product and Revenue database.
Use this GraphQL API method to retrieve summary data of Journeys and each campaign within those Journeys. If you want individual contact data for Journey campaigns, then you should use the Campaigns API.