# 2. Reading / Writing Data ## PDA Data I/O 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](/build/advanced-topics/pda-authentication/password-management/tutorials/android-kotlin/4.-data-debits.md), a system of consented data exchange. ## Writing Data to PDA ### Make network requests `Hat API Android` offers a general method to create network requests: ```kotlin HATNetworkManager().postRequest( url, body: String, headers: Map, 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](https://restfulapi.net/http-methods/) * `contentType` is the content-type of the request, you can find more [here](https://www.w3.org/Protocols/rfc1341/4_Content-Type.html) * `headers` 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 be `isSuccess(var statusCode: Int?, var error: Error?, var json: Json?, var resultString: String?, var token: String?)` if the request was successful or `HasFailed(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 the `200..299` range is a success and `400..599` is failure. You can learn more about the different status codes [here](https://httpstatuses.com). * The `result` is `Json` type of `Fuel`, can be found [here](https://github.com/kittinunf/Fuel). * The `token` is a refreshed token returned from the `PDA`. 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 the `200..299` range is a success and `400..599` is failure. You can learn more about the different status codes [here](https://httpstatuses.com). * The `result` is `JSON` type of `Fuel`, can be found [here](https://github.com/kittinunf/Fuel). Usually it will hold more info about the failure. ## Write data Let's say we want to save the `randomStructure` below in our `PDA`: ```javascript { "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 be ```kotlin HATNetworkManager().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: ```kotlin when (result){ is ResultType.IsSuccess->{ //do something.... } is ResultType.HasFailed->{ //do something.... } } ``` A successful response will have `statusCode` 201 and look like this: ```javascript { "endpoint": "randomdata", "recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115", "data": { "value 1": "random", "Int value": 0 } } ``` * `endpoint` is the `path` that 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: ```javascript { "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 are going to use the same request again but `method` will be `GET` instead of `POST`: ```kotlin HATNetworkManager().getRequest( url, parameters: List>, headers: Map?, 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: ```kotlin HATNetworkManager().getRequest( "https://postman.hubat.net/api/v2.6/data/dataswift-sandbox/randomdata", parameters: List>, 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: ```kotlin when (result){ is ResultType.IsSuccess->{ //do something.... } is ResultType.HasFailed->{ //do something.... } } ``` A successful response will have `statusCode` 200 and look like this: ```javascript { "endpoint": "randomdata", "recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115", "data": { "value 1": "random", "Int value": 0 } } ``` * `endpoint` is the `path` that 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: ```javascript { "error": "Not Authenticated", "message": "Not Authenticated" } ``` * `error` is the error that has occurred * `message` a more descriptive message about the `error` that has occurred ## Update data Let's say that we want to change our original example: ```javascript { "value 1": "random", "Int value": 0 } ``` To something like this: ```javascript { "value 1": "random", "newValue": true, "Int value": 1 } ``` To update the data, the HTTP `method` has to change to `PUT`: ```kotlin HATNetworkManager.putRequest( url, body: String, headers: Map, 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: ```kotlin 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` 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: ```kotlin when (result){ is ResultType.IsSuccess->{ //do something.... } is ResultType.HasFailed->{ //do something.... } } ``` A successful response will have `statusCode` 201 and look like this: ```javascript { "endpoint": "randomdata", "recordId": "cf2c4ad5-bbb2-4a0e-8aaa-d3be8b76e115", "data": { "value 1": "random", "newValue": true, "Int value": 1 } } ``` * `endpoint` is the `path` that 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: ```javascript { "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: ```kotlin HATNetworkManager().deleteRequest( url, body: String, headers: Map, 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: ```kotlin 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: ```javascript { "records": 5 } ``` A successful response will have `statusCode` 200 and look like this: ```javascript { "message": "All records deleted" } ``` A request that has failed will look like this: ```kotlin { "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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dataswyft.com/build/advanced-topics/pda-authentication/password-management/tutorials/android-kotlin/2.-reading-writing-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.