The SPACEtag® Objects API allows you to specify how much of your data you want to be returned from the Object Store.
Get Only The Required Fields #
By specifying the fields you want returned in your request, you can reduce the amount, and simplify the data that is returned in the response. For example, when accessing the contacts.person Collection you might only be interested in their name and email address. All of the other data in the Object is surplus to requirements and just increases the amount the network bandwidth consumed and can increase processing time.
To limit the fields we want returned, we use the _$getFields command. Commands in the Objects API always start with _$ so that they can be distinguished from field names. If you don’t specify this command then all fields will be returned with the Object.
So in the above example, the following request will return just the first_name, last_name and email fields:
GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&_$getFields=first_name,last_name,emailYou can also combine the _$getFields command with other commands, for example the _$sortBy command to return the Objects in a specific order:
GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&_$getFields=first_name,last_name,email&_$sortBy=last_name,first_nameGet Only A Certain Number of Objects #
Let’s say you only want to get a certain number of Objects from the Collection – for example the top ten people by age, then you can do this using the _$maxRows command. This will tell the data processor to only return the first n number of Objects in the response. The following command will return the first ten results it finds in the contacts.person Collection:
GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&_$getFields=first_name,last_name,email&_$maxRows=10However, in the above example we don’t what order the data will found – in fact by default it will be returned in the order of the uuid field which is purely a unique identifier for each Object and essentially meaningless in this context. So we can expand this request by including the _$sortBy command discussed above.
In the following example, we are going the get the first ten people in order of their age using the dob field – so essentially the ten oldest people:
GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&_$getFields=first_name,last_name,email&_$maxRows=10&_$sortBy=dobSo here, the data processor will get the People Objects in order of date of birth ascending (oldest to youngest) and return the first 10 in the list. Note, obviously, if there are less than ten people in the results, it will only return those that are available.
Data Paging #
What about if we want to get the next set of ten people? Well, expanding on the above example, we can do this using the _$rowStart command. This allows us to specify whereabouts in the results we want to start returning the Objects. This is useful when you want to page through your Collection in small chunks, for example when presenting your data in a table on Web app.
So let’s return the next set of results – or “page” – in the previous example. We’ve got rows 1 to 10 – we’re now going to get 11 to 20 in the list:
GET https://api.spacetagcloud.net/objects/v1/action?object=contacts.person&_$getFields=first_name,last_name,email&_$maxRows=10&_$rowStart=11&_$sortBy=dobIn this example, the data processor will get the People Objects in order of date of birth (oldest to youngest) and then return 10 Objects starting from number 11 in the list. To get the next 10, you would simply specify _$rowStart=21 in the request.