Getting started with Dataswift’s Developer Portal — Creating a new application
This article is the second part of our “Getting started with Dataswift’s Developer Portal” series, which covers:
- Registration
- Creating a new application
- Updating and submitting an application.
In the previous blogpost, we looked at the registration process and the testing roles. This article will show us how to create a new application in the Dataswift’s Developer Portal and how to start testing by writing and reading some data with our testing user.
Create a new application
First, we need to sign in to the Developer Portal. If you don’t have an account yet, please refer to the previous blogpost, which provides the instructions to do this.
Next, we need to select “My Apps” -> “Create” and then fill out all the necessary information needed to create our first application.
Application name — A human-readable name of the application.
Application website — A URL where more information about the application can be found.
Application ID — A unique application identifier. Must not contain spaces or special characters.
Application namespace — The unique application namespace. This will define the domain under which the application will be able to read/write data. It must not contain spaces or special characters.
Country — The organization’s country.
Platforms — The platforms this application will support.
And for every selected platform, 2 additional fields are needed:
Application link — A URL where users can learn more about the application.
Callback URI — A callback URI that will be used during authentication with the HAT.
Our first application has been created!
Please note that the application can take up to 30 minutes to be available for testing.
The application ID for the testing app needs a “-dev” suffix.
eg. test-app-1991 will be available as test-app-1991-dev for testing.
Interact with the HAT
At this step, we will authenticate with the HAT and then write and read some data from our testing role.
Authentication
In our applications, we cannot ask our users to enter their passwords. They can only do so through their HAT PDA. Once they have entered their password, the callback URL from our app will redirect them back to our application with an authentication token.
In the following example, we will use the testing role that the Developer Portal created for us at registration.
Redirect the user to the Login page to get the Access token
First, we need to redirect the user to their HAT PDA where they can enter their password to complete the authorization.
We will need to build the URL using our app ID, our callback URI and a URI in case of failure. The URL will look similar to this:
https://<hat-url>/#/hatlogin?
name=<application-id>
&redirect=<redirect>
&fallback=<fallback>
hat-url — the HAT PDA’s unique URL. eg. testing.hubat.net
application-id — Our application ID. eg. test-app-1991-dev
redirect — The callback URI for our application. eg. test-app://authenticate
fallback — The URI will be called on authorization failure.
Upon successful login, the HAT will verify if the application has been granted all the permissions it needs. If not, the HAT user will need to do so for the app to access their HAT.
Lastly, the user will be redirected back to our application with the authentication token attached. This should be stored for subsequent API calls:
test-app://authenticate?token=eyJ0eXAiOiJKV1Qi….
Read/write data into the HAT
Once the HAT user is authenticated and we have the authentication token, we can easily write some data onto the HAT.
For this step, we will need the application’s unique namespace. By default, we can only read and write data there, but we can choose multiple endpoints under the namespace. Eg. “test-app/locations” and “test-app/profile”
Write Data
To write some data in the HAT, we need to make a POST request:
https://<hat-url>/api/v2.6/data/<namespace>/<endpoint>
hat-url — is the HAT name followed by the cluster.
namespace — is the unique application’s namespace.
endpoint — is the endpoint where we need to store the data.
Example:
https://testleytis1003dev.hubat.net/api/v2.6/data/test-app-1991-dev/my-tasks
We need to pass the authentication token and the content-type as Headers:
x-auth-token: <auth-token>
content-type: application/json
As a body, we can have a valid JSON object:
Once the request is successful, the API will return the data that we stored along with any extra details about the endpoint and the recordId.
Read Data
As we have already stored some data into the HAT PDA, we can fetch them by making a GET request to the same endpoint:
https://<hat-url>/api/v2.6/data/<namespace>/<endpoint>
Example:
https://testleytis1003dev.hubat.net/api/v2.6/data/test-app-1991-dev/my-tasks
We need to pass the authentication token as Headers:
x-auth-token: <auth-token>
And the HAT API will return an Array of the records that are already stored in that endpoint.
To learn more about HAT Login and storing data into the HAT please visit:
What’s next
In the next blogpost: “Updating and submitting an application” we will learn:
- How to update our application,
- How to prepare the application to go live, and
- How to keep testing and updating the live version of the app.
