Genii Weblog
Fancy tricks with REST API - Part 1
Tue 19 Jan 2021, 09:23 PM
Tweetby Ben Langhinrichs
At first glance, it may seem like REST APIs are inherently simple. You retrieve the data from a record or collection of records, and then you do your stuff. If you need to create, update records, or delete records, you can do that as well. But when you are building a proper application, there are many other things to consider. Two key factors are:
1) How much data do you need from any given record, and which records do you need it from? If there is related data in another record, can you get it without pulling in loads of stuff you don't need?
2) What format should the data be in? How should it be structured or grouped for maximum usability? While you can certainly write code in your application to reformat or restructure, that adds complexity and room for error on your client.
Using the Curb Appeal database I showed in Getting data from Domino with Exciton Boost (and companion post with code samples,Data from Domino: nuts and bolts of REST calls), let's look at a few of the "fancy tricks", also known as "useful features" of Exciton Boost 4.6.1 (released today). With Exciton Boost, you can specify exactly which information you need. In the code sample post above, I use the following call:
GET /CurbAppeal.nsf/api/boost/documents/524C08BF648BE77A85257B8600798F5B?metadata=false HTTP/1.1
X-Items-List: StreetAddress+", "+City+", "+State=Address,Bdrms,Full=Bathrooms,Half=Half-Baths,Photo[Graphic 1]
The resulting JSON is shown below. Note that we used formula language for the address, but I've shown that before.
Fancy trick 1: - Grouping stuff together
If you look up at the original screen capture, you can see that the bathrooms are grouped together. That is because people logically expect full bathrooms and half bathrooms to go together. So, how can we make our JSON, and thus our eventual JavaScript object, reflect this natural grouping? Pretty simple, really. I just change the X-Items-List header to the following (changes shown in Blue).
X-Items-List: StreetAddress+", "+City+", "+State=Address,Bdrms,Full=Bathrooms/Full,Half=Bathrooms/Half,Photo[Graphic 1]
If successive items are defined with that =group/alias syntax, the result will be grouped in an object named for the group. Now, we get this JSON, and can act on the whole Bathrooms object in our app.
Fancy trick 2: - Using rich text as a data source rather than rendering
If you look up at JSON right above the Fancy trick 1 headline, you can see that it is HTML encapsulated in JSON. That is handy if you want to display it, but not if you want to use it as a data object. You could by parsing the HTML, but you shouldn't have to. A similar example is in the columns of bullet points you can see in the top graphic under the title Features. What if you want those bullet points as separate data strings rather than HTML? Exciton Boost makes it easy to define the data structure you want rather forcing you to parse and interpret.
We change the reference from Photo[Graphic 1] to Photo[Graphic *] to mean all graphics in the rich text field named Photo. Then, we add in a series of chunk properties related to a graphic, ;$GraphicOffset;$GraphicFormat;%GraphicHeightPX;%GraphicWidthPX. These will all be grouped together. Finally, we add the {A} which makes this an array of objects, one per graphic. If there were no graphics, it would be an empty array.
X-Items-List: StreetAddress+", "+City+", "+State=Address,Bdrms,Full=Bathrooms/Full,Half=Bathrooms/Half,Photo[Graphic *;$GraphicOffset;$GraphicFormat;%GraphicHeightPX;%GraphicWidthPX]{A}
Since there is only one graphic in this rich text field, the result looks like this:
We can iterate through the array to get to the objects and their values, but if we don't want to do that, we could simply change the {A} to {O}, and we would get an object with named sub-objects:
X-Items-List: StreetAddress+", "+City+", "+State=Address,Bdrms,Full=Bathrooms/Full,Half=Bathrooms/Half,Photo[Graphic *;$GraphicOffset;$GraphicFormat;%GraphicHeightPX;%GraphicWidthPX]{O}
Now, we could use JSON.parse to get the JavaScript object and refer to Photo.Graphic_1.GraphicHeightPX to get the value 251. As a note, capitalization follows the item definitions, so if you prefer camel case, just make it:
X-Items-List: StreetAddress+", "+City+", "+State=address,bdrms,Full=bathrooms/full,Half=bathrooms/half,photo[graphic *;$graphicOffset;$graphicFormat;%graphicHeightPX;%graphicWidthPX]{O}
Finally, it is worth noting that if only a single property is specified, we don't need objects. If we wanted to get all the bullet items under that Features column. we could use:
X-Items-List: StreetAddress+", "+City+", "+State=address,bdrms,Full=bathrooms/full,Half=bathrooms/half,col1[BulletList *;$UnformattedText]{A}=bullets
=> Request a free Exciton Boost eval in January, and if you later purchase a license. we'll add in four hours of development assistance, a $700 value. <=
I will have a couple more Fancy Tricks tomorrow.
Copyright © 2021 Genii Software Ltd.
What has been said: