2. Reading / Writing Data
The PDA is a data store. This means that you can read and write any data you want, be it a passport, your health records or any data you can think of.
HAT API Android
has built-in support for reading or writing data to your PDA
.This section describes the mechanism of writing data. For reading, this is done through data-debits, a system of consented data exchange.
Hat API Android
offers a general method to create network requests:HATNetworkManager().postRequest(
url,
body: String,
headers: Map<String, String>,
completion: completionCallback)
url
is the URL to send the request toheaders
is the additional headers of the request, this field can be an empty dictionary,mapOf("","")
completion
is a callback function to execute when the request has finished. The result type of the callback can either beisSuccess(var statusCode: Int?, var error: Error?, var json: Json?, var resultString: String?, var token: String?)
if the request was successful orHasFailed(var statusCode: Int?, var error: Error?, var json: Json?, var resultString: String?, var token: String?)
if the request has failed.
The result type is an
enum
. Depending if the request was a success or a failure it will have the right type. When the request is successful, the result type will include:- A boolean value
isSuccess
, indicating if the request was successful. It may be that the request triggers the successful result type but the isSuccess is false, for example, a 404 response. - The
statusCode
of the request. Usually the200..299
range is a success and400..599
is failure. You can learn more about the different status codes here. - The
token
is a refreshed token returned from thePDA
. It's optional and sometimes can be null or empty.
When the request has failed, the result type will include:
- The
error
that has occurred with the request, e.g. no internet connection or time out. - The
statusCode
of the request. Usually the200..299
range is a success and400..599
is failure. You can learn more about the different status codes here. - The
result
isJSON
type ofFuel
, can be found here. Usually it will hold more info about the failure.
Let's say we want to save the
randomStructure
below in our PDA
:{
"value 1": "random",
"Int value": 0
}
The
URL
that the data will be saved is https://$hatAddress/api/v2.6/data/$path
.If the
hatAddress
is postman.hubat.net
and the path
is randomdata
then the URL
will be: https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata
.The
path
is formed by your app name, dataswift-sandbox
, and the rest of the path, randomdata
. It can also be folder/something/data/random
. How deep the path will be depends on the data structure that your app uses to navigate to different files.To write data to the
PDA
, we also need the user's token in the headers of the request. The header you need to add is x-auth-token
along with the token retrieved from the KeyStore
. NEVER save the token in a non-encrypted database.Using the function from
Hat API Android
that will beHATNetworkManager().postRequest(
"https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata",
parameters: randomStructure,
headers: mapOf("x-auth-token" to token,"Content-Type" to "application/json"),
completion: completionCallback)
Based on the type of the
completionCallback
you might have gotten the data back or you might get an error. Your app should know how to react in both scenarios:when (result){
is ResultType.IsSuccess->{
//do something....
}
is ResultType.HasFailed->{
//do something....
}
}
A successful response will have
statusCode
201 and look like this:{
"endpoint": "randomdata",
"recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115",
"data": {
"value 1": "random",
"Int value": 0
}
}
endpoint
is thepath
that the file resides,https://$hatAddress/api/v2.6/data/$path
recordId
is the record identifier in thePDA
. It's useful for when you want to delete the file for example.data
is the data structure that you have saved in thePDA
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
is a more descriptive message about theerror
that has occurred
If we want to read data we are going to use the same request again but
method
will be GET
instead of POST
:HATNetworkManager().getRequest(
url,
parameters: List<Pair<"key", value?>>,
headers: Map<String, String>?,
completion: completionCallback)
If we make the same assumptions again, the
hatAddress
is postman.hubat.net
, the path
is randomdata
and the x-auth-token
in the headers includes the token, then the call will look like below:HATNetworkManager().getRequest(
"https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata",
parameters: List<Pair<String, Any?>>,
headers: mapOf("x-auth-token" to token,"Content-Type" to "application/json"),
completion: completionCallback)
Notice that since we want to read data and not write, we don't include any parameters.
Based on the type of the
completionCallback
you might have gotten the data back or you might get an error. Your app should know how to react in both scenarios:when (result){
is ResultType.IsSuccess->{
//do something....
}
is ResultType.HasFailed->{
//do something....
}
}
A successful response will have
statusCode
200 and look like this:{
"endpoint": "randomdata",
"recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115",
"data": {
"value 1": "random",
"Int value": 0
}
}
endpoint
is thepath
that the file resides:https://$hatAddress/api/v2.6/data/$path
recordId
is the record identifier in thePDA
. It's useful for when you want to delete the file for example.data
is the data structure that you have saved in thePDA
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
a more descriptive message about theerror
that has occurred
Let's say that we want to change our original example:
{
"value 1": "random",
"Int value": 0
}
To something like this:
{
"value 1": "random",
"newValue": true,
"Int value": 1
}
To update the data, the HTTP
method
has to change to PUT
:HATNetworkManager.putRequest(
url,
body: String,
headers: Map<String, String>,
completion: completionCallback)
If we make the same assumptions again, the
hatAddress
is postman.hubat.net
and request and the x-auth-token
in the headers includes the token, then the call will look like below:HATNetworkManager().putRequest(
"https://postman.hubat.net/api/v2.6/data",
body: body,
headers: ["x-auth-token" to token, "Content-Type" to "application/json"],
completion: completionCallback)
Where
parameters
is an array of Key-value pair
of type Map<String: Any>
representing the new structure that we want to update. Mind the brackets, it has to be an array even if it's just one element.Based on the type of the
completionCallback
you might have gotten the data back or you might get an error. Your app should know how to react in both scenarios:when (result){
is ResultType.IsSuccess->{
//do something....
}
is ResultType.HasFailed->{
//do something....
}
}
A successful response will have
statusCode
201 and look like this:{
"endpoint": "randomdata",
"recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115",
"data": {
"value 1": "random",
"newValue": true,
"Int value": 1
}
}
endpoint
is thepath
that the file resides:https://$hatAddress/api/v2.6/data/$path
recordId
is the record identifier in thePDA
. It's useful for when you want to delete the file for example.data
is the data structure that you have saved in thePDA
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
is a more descriptive message about theerror
that has occurred
If we now want to delete the file we have just created, we need to create a
DELETE
request:HATNetworkManager().deleteRequest(
url,
body: String,
headers: Map<String, String>,
completion: completionCallback)
If we make the same assumptions again, the
hatAddress
is postman.hubat.net
and request and the x-auth-token
in the headers includes the token, then the call will look like below:HATNetworkManager().deleteRequest(
"https://postman.hubat.net/api/v2.6/data",
body: body,
headers: mapOf("x-auth-token" to token),
completion: completionCallback)
Where
body
in this case is the recordId
of the entry that we want to delete. We can also delete multiple entries with one request using more parameters. If the recordId
is 5 then the body
will be:{
"records": 5
}
A successful response will have
statusCode
200 and look like this:{
"message": "All records deleted"
}
A request that has failed will look like this:
{
"error": "Not Authenticated",
"message": "Not Authenticated"
}
error
is the error that has occurredmessage
is a more descriptive message about theerror
that has occurred
Last modified 1yr ago