2. Reading / Writing Data

PDA Data I/O

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 data-debits for details about reading data and our system of consented data exchange.

Make network requests

Hat for iOS offers a general method to create network requests:

HATNetworkManager.asynchronousRequest(
  url,
  method: .post,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "text/string",
  parameters: ["key": value],
  headers: ["key": value],
  completion: completionCallback)

• url is the URL to send the request to

• method is the HTTP method of the request, you can find the different methods here

• encoding is the encoding method of the request, default types of Alamofire

• contentType is the content-type of the request, you can find more here

• 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 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 here.

• The result is JSON type of SwiftyJSON, can be found here.

• 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.

• 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 here.

• The result is JSON type of SwiftyJSON, and can be found here. Usually it will hold more info about the failure.

Write data

Let's say we want to save the randomStructure below in our PDA:

{
  "value 1": "random",
  "Int value": 0
}

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:

HATNetworkManager.asynchronousRequest(
  "https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata",
  method: .post,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "application/json",
  parameters: randomStructure,
  headers: ["x-auth-token": token],
  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:

switch response {

case .error(let error, let statusCode, let result):

    // do something....
case .isSuccess(let isSuccess, let statusCode, let result, let token):

    // 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 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": "Not Authenticated",
  "message": "Not Authenticated"
}

• error is the error that has occurred

• message is a more descriptive message about the error that has occurred

Read data

If we want to read data, we will use the same request again but the method will be GET instead of POST:

HATNetworkManager.asynchronousRequest(
  url,
  method: .get,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "text/string",
  parameters: ["key": value],
  headers: ["key": value],
  completion: completionCallback)

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:

HATNetworkManager.asynchronousRequest(
  "https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata",
  method: .get,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "application/json",
  parameters: [:],
  headers: ["x-auth-token": token],
  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 have gotten an error. Your app should know how to react in both scenarios:

switch response {

case .error(let error, let statusCode, let result):

    // do something....
case .isSuccess(let isSuccess, let statusCode, let result, let token):

    // 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 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": "Not Authenticated",
  "message": "Not Authenticated"
}

• error is the error that has occurred

• message is a more descriptive message about the error that has occurred

Update data

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
}

In order to update the data, the HTTP method has to change to PUT:

HATNetworkManager.asynchronousRequest(
  url,
  method: .put,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "text/string",
  parameters: ["key": value],
  headers: ["key": value],
  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.asynchronousRequest(
  "https://postman.hubat.net/api/v2.6/data",
  method: .put,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "application/json",
  parameters: parameters,
  headers: ["x-auth-token": token],
  completion: completionCallback)

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:

switch response {

case .error(let error, let statusCode, let result):

    // do something....
case .isSuccess(let isSuccess, let statusCode, let result, let token):

    // 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 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": "Not Authenticated",
  "message": "Not Authenticated"
}

• error is the error that has occurred

• message is a more descriptive message about the error that has occurred

Delete data

If we now want to delete the file we have just created we need to create a DELETE request:

HATNetworkManager.asynchronousRequest(
  url,
  method: .delete,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "text/string",
  parameters: ["key": value],
  headers: ["key": value],
  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.asynchronousRequest(
  "https://postman.hubat.net/api/v2.6/data",
  method: .delete,
  encoding: Alamofire.JSONEncoding.default,
  contentType: "application/json",
  parameters: parameters,
  headers: ["x-auth-token": token],
  completion: completionCallback)

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:

{
  "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 occurred

• message is a more descriptive message about the error that has occurred