SPACEtag® Objects is an API-driven data store, which means you use standard REST API commands to add, fetch, update and delete your data objects. The general terms for these data operations is called “CRUD” – which stands for Create, Read, Update and Delete. To perform these operations, you make requests using specific HTTP methods, namely POST, GET, PUT and DELETE. In order to use the Objects API, some knowledge of using REST APIs is required.
Postman Tool #
When developing your application, and building and testing your Objects, we thoroughly recommend using the free Postman API Platform. It is specifically designed for building and using APIs and all standalone examples and tutorials within the SPACEtag® Cloud eco-system will be based on Postman. Postman supports variables and pre-defined API keys to help you speedily build and test API data projects.
Example GET request in Postman to get all “Organisation” Objects from the “Contacts” Module.
HTTP Methods #
| Object Data Operation | HTTP Method for API |
|---|---|
| CREATE (Add a new Object) | POST |
| READ (Get Object data) | GET |
| UPDATE (Update an existing Object) | PUT |
| DELETE (Delete an existing Object) | DELETE |
Authentication #
In order to make requests to your Objects Data Store, you need to authenticate your requests using your SPACEtag® Engine Authentication Keys. Your SPACEtag® Cloud account also needs to have the Objects module included within your subscription. Please refer to this article for information about obtaining your keys.
To make it easier for testing and accessing your Objects in Postman, you can pre-define your authentication credentials in your Postman Workspace. Note that the following details in this section only apply if you are using Postman. If you are using other tools then refer to the user guide for the particular tool you are using.
Postman – Storing the Credentials in Variables #
The first thing to do is store your keys as Environment Variables for your Workspace in Postman. Do this in the Environments tab. You can either create the variables in the “Globals” environment, or create a dedicated environment for your project.
Then add your API Key and App UUID credentials as variables that you can then refer to when creating requests in Postman.
Postman – Pre-defining Authentication for All Requests #
Within Postman, we can now set up Authentication for all requests we make within a Collection. This means we only need to set it up once and not worry about it again as we add more requests. It also means that if we ever have to change our credentials then we only need to replace them in the variables above.
Specifying the API Key #
In your Collection, select the “Authorization” tab – this will set up the authorisation method for every request in that Collection.
In our case, we will set it up as shown in the following screen snip, using these settings:
- Auth Type: API Key
- Key:
x-api-key(this is the x-api-key Header that we send with our request) - Value:
{{objects-api-key}}(this is a reference to the variable we specified above) - Add to: Header (this adds our authentication key to the HTTP Header when we make the request to the API gateway)
Specifying the App UUID #
When we make a request to the Objects API, we also need to specify the App UUID header (x-spacetag-app-uuid). However, Postman only allows us to specify one header value in the Authorization tab, so we need to create a little Pre-request Script in Postman. This script will get the environment variable we specified above and add it to a header in the request before it is sent to the API gateway.
Go to the Scripts tab for the Collection and enter the script as follows (it’s actually Javascript that Postman uses):
or copy and paste from here:
const appUUID = pm.environment.get("objects-app-uuid");
pm.request.addHeader({key: "x-spacetag-app-uuid", value: appUUID});Postman – Pre-defining Other Values #
Using Postman Variables you can pre-define values for other purposes as well, at the Collection, Environment or Global level. For example, you might want to create a variable that contains the Objects API base end-point URL so that you don’t need to keep having to remember and enter it.
The above setting means we can now use the {{objects-api-base-url}} placeholder variable in our Postman requests.
Ready to Start Developing #
Now we’re all set up, we can start our development and testing. The following articles will give you examples of how to make Create, Read, Update and Delete requests to a contacts.person Object. The approach will be the same for every single Object within your Data Store.
The first thing to note is that in every request you make, you always need specify the Object Collection you are working with. This is done using the “object” parameter in either the Query Param for a GET (Read) and DELETE request, or the JSON payload for a POST (Create) and PUT (Update) request.