When designing Engage, we wanted to ensure that users could have simple and straightforward API access to data no matter their data or access pattern. Although we’ve previously written on how Engage’s easy access to data can let marketing teams power communications in real time, I think it’s worth exploring the different ways users can interact and access their Engage data and review a few use cases for developers or technical marketers to use data in real time.
To begin, let’s establish a sample use case. Let’s imagine we are working with our City & Glory furniture brand and are trying to use data we have to power marketing channels. In this example, we have two Engage data sets:
- ITEMS: our data set of items we would like to showcase in our mailings, including inventory and sale price
- STORES: our data set of our furniture store locations, with their store name, address, and hours of operation:
Let’s talk through the different ways we can fetch this data and how it would be returned to the consumer. In these examples, I’ll be posting the URL where each resource would be located. Engage authentication requires a simple bearer token as authentication, which we will assume has been passed when requesting data.
Use Case 1 – Fetching an Item Per Call
Initially, let’s just try to fetch a single item from our Engage data set in a single call. In this case, we will try to fetch item 1 from our ITEMS data set. The URL we would reach is:
https://api.messagegears.net/v5/engage/context?key=ITEMS-1
The ‘key’ query param indicates that we are only fetching a single data entry, and to return the JSON body of that entry. In this case, we are querying engage for item id 1 from our ITEMS data set (ITEMS-1). The call above would return the following JSON body:
HTTP: 200 OK
{
“Item_Id”: “1”,
“Name”: “Plush Sofa”,
“Inventory”: “15”,
“Normal Price”: “$750”,
“Sale Price”: “$600”
}
Returned in this response is a simple object of key-value pairs detailing the information stored in Engage. This call-and-response pattern is useful when the user will only ever be fetching a single item and traversing the JSON structure for specific pieces of data.
Use Case 2 – Fetching Multiple Items from a Single Data Set
Let’s broaden our use case to try and fetch multiple items. Perhaps we are displaying an email showing the user the top 3 suggested items for him or her, and we would like to fetch all three items in a single call. Our call here would be:
https://api.messagegears.net/v5/engage/context?data=ITEMS-1,ITEMS-2,ITEMS-3
The ‘data’ query param indicates that we are fetching multiple data points, and will be expecting multiple responses. These calls are comma delimited query parameters defining the data points we are requesting (ITEMS 1,2, and 3). In this case, the call above would return the following JSON body:
HTTP: 200 OK
{
“ITEMS-1”: {
“Item_Id”: “1”,
“Name”: “Plush Sofa”,
“Inventory”: “15”,
“Normal Price”: “$750”,
“Sale Price”: “$600”
}
,
“ITEMS-2”: {
“Item_Id”: “2”,
“Name”: “LEATHER CHAIR”,
“Inventory”: “25”,
“Normal Price”: “$500”,
“Sale Price”: “$350”
},
“ITEMS-3”: {
“Item_Id”: “3”,
“Name”: “Wooden Table”,
“Inventory”: “50”,
“Normal Price”: “$350”,
“Sale Price”: “$275”
}
}
Because we have specified multiple data points, the Engage response returns a set of key and object pairs of the requested items. This allows users to easily search and find data when searching for multiple items across a single data set
Use Case 3 – Fetching Multiple Items From Multiple Data Sets
Finally, let’s imagine that we would like to show the user multiple items from their nearest store, as well as the store’s name, address, and hours of operation. What we essentially want to do is join data across multiple sets into a single call — which we can do using the ‘data’ parameter as seen here:
https://api.messagegears.net/v5/engage/context?data=ITEMS-1,ITEMS-2,STORES-1
Notice how in this example we are now calling for two items from the ITEMS data set, and a single item from the STORES data set. Our return is now:
HTTP: 200 OK
{
“ITEMS-1”: {
“Item_Id”: “1”,
“Name”: “Plush Sofa”,
“Inventory”: “15”,
“Normal Price”: “$750”,
“Sale Price”: “$600”
}
,
“ITEMS-2”: {
“Item_Id”: “2”,
“Name”: “LEATHER CHAIR”,
“Inventory”: “25”,
“Normal Price”: “$500”,
“Sale Price”: “$350”
},
“STORES-1”: {
“Store_id”: “1”,
“Address”: “191 Peachtree St, Atlanta GA, 30309”,
“Store Name”: “City & Glory of Midtown Atlanta”,
“Hours of Operation”: “9 a.m. – 6 p.m.”
}
}
Just like before, we have a set of key and object pairs, but this time spanning multiple data sets. This is incredibly useful for assembling data stored on different indices, and is extensible to different data types and sizes. Engage can support up to 25 data points returned per call, and can join across up to 25 different data sets.
Missing and Disjointed Data
When designing Engage, we understood that a litany of things could prevent the data specified by the API call to be available. That’s why we have made use of the HTTP status codes to inform the caller as to what data is available.
Let’s imagine in the above scenario that Item 2 was not available in the Engage data store, but was present in the API call. In that case, our URL would remain the same:
https://api.messagegears.net/v5/engage/context?data=ITEMS-1,ITEMS-2,STORES-1
But, the data returned (as well as our HTTP response code) would be different:
HTTP: 207 Multi-Status
{
“ITEMS-1”: {
“Item_Id”: “1”,
“Name”: “Plush Sofa”,
“Inventory”: “15”,
“Normal Price”: “$750”,
“Sale Price”: “$600”
}
,
“STORES-1”: {
“Store_id”: “1”,
“Address”: “191 Peachtree St, Atlanta GA, 30309”,
“Store Name”: “City & Glory of Midtown Atlanta”,
“Hours of Operation”: “9 a.m. – 6 p.m.”
}
}
Because it would be awkward (and potentially misleading) to include the missing data points in the API response, we simply omit them and allow the HTTP 207 status code to inform the user that only some of the requested resources were available. Similarly, if none of the requested resources are available, we return a simple HTTP 404 status code to indicate that the resources could not be found within the data store.
Have any more questions on how we created Engage, or have ideas on other things you would like to do with multiple data stores? Let us know: @messagegears.
Johntavious Barkley
Johntavious is a Software Engineer for MessageGears with a special interest in cloud and system architecture. He enjoys finding solutions to complex engineering challenges where scalability and performance are critical.
