2. Reading / Writing Data
Last updated
Was this helpful?
Last updated
Was this helpful?
A PDA is a data store. That means you can read and write any data you want, be it a passport, your health records or any data you can think of.
HAT for iOS has built-in support for reading or writing data to your PDA.
This section describes the mechanism of writing data. Make sure to read all the way to for details about reading data and our system of consented data exchange.
Hat for iOS offers a general method to create network requests:
url is the URL to send the request to
method is the HTTP method of the request, you can find the different methods
encoding is the encoding method of the request, default types of Alamofire
contentType is the content-type of the request, you can find more
parameters is the parameters of the request, this field can be an empty dictionary, [:]. Also, if the request method is POST, then this will be the body of the request and the actual data structure that will be saved on the PDA.
headers is the additional headers of the request, this field can be an empty dictionary, [:]
completion is a callback function to execute when the request has finished. The result type of the callback can either be
isSuccess(isSuccess: Bool, statusCode: Int?, result: JSON, token: String?) if the request was successful or error(error: Error, statusCode: Int?, result: JSON?)if the request has failed.
The result type is an enum. Depending on whether 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 the response was 404.
The token is a refreshed token returned from the PDA. It's optional and sometimes can be nil 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.
Let's say we want to save the randomStructure below in our PDA:
The URL in which 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.
In order 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 Keychain. NEVER save the token in an unencrypted database.
Using the function from Hat-for-iOS that will be:
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:
A successful response will have statusCode 201 and look like this:
endpoint is the path where the file resides: https://\(hatAddress)/api/v2.6/data/\(path)
recordId is the record identifier in the PDA. It's useful for when you want to delete the file, for example.
data is the data structure that you have saved in the PDA
A request that has failed will look like this:
error is the error that has occurred
message is a more descriptive message about the error that has occurred
If we want to read data, we will use the same request again but the method will be GET instead of POST:
Making 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:
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 have gotten an error. Your app should know how to react in both scenarios:
A successful response will have statusCode 200 and look like this:
endpoint is the path where 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 is the error that has occurred
message is a more descriptive message about the error that has occurred
Let's say that we want to change our original example:
To something like this:
In order to update the data, the HTTP method has to change to PUT:
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:
Where parameters is an array of Key-value pair of type [String: Any] represent 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:
A successful response will have statusCode 201 and look like this:
endpoint is the path where the file resides, https://\(hatAddress)/api/v2.6/data/\(path)
recordId is the record identifier in the PDA. It's useful for when you want to delete the file for example.
data is the data structure that you have saved in the PDA.
A request that has failed will look like this:
error is the error that has occurred
message is a more descriptive message about the error that has occurred
If we now want to delete the file we have just created we need to create a DELETE request:
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:
Where parameters in this case is the recordId of the entry we want to delete. We can also delete multiple entries with one request using more parameters. If the recordId is 5 then the parameters will be:
A successful response will have statusCode 200 and look like this:
A request that has failed will look like this:
error is the error that has occurred
message is a more descriptive message about the error that has occurred
The statusCode of the request. Usually the 200..299 range is a success and 400..599 is failure. You can learn more about the different status codes .
The result is JSON type of SwiftyJSON, can be found .
The statusCode of the request. Usually the 200..299 range is a success and 400..599 is failure. You can learn more about the different status codes .
The result is JSON type of SwiftyJSON, and can be found . Usually it will hold more info about the failure.