# Contracted PDA API ## Contracted PDAs Implementation Guide The Contracted PDA feature allows an application developer to gain short-lived read-and-write access to PDAs that have given prior permissions for such access. You must apply to gain access to the Contracted PDA feature. The process to do this is outside the scope of this document. Please contact your Dataswift account manager or for more information. Once access to the Contracted PDA feature is granted, the application developer will be assigned a Contract which defines the namespaces for which read and/or write access are requested. The contract will be tied to the application designed by the developer. **When the PDA owner signs on to the application, the HMI screen presented will ask for permissions to have the PDA join the Contract.** This document will show you how to read and write data to the PDA using the Contracted PDA feature. You need to be given access credentials to the Contracted PDA feature by Dataswift. ### **Access Credentials** The access credentials include 2 pieces of information: 1. Contract Id - **\** * The Contract Id references the assigned Contract, described in the Introduction above. The contract definition can be viewed at [https://dex.dataswift.io/api/v1.1/applications/\](https://dex.dataswift.io/api/v1.1/applications/** * This is the private key that must be kept safe and unexposed. * This key is required to obtain a Short-Lived token which can then be used to access all the PDAs that have joined the Contract. #### **Getting the Short-Lived Access Token** The Long-Lived Token is required to obtain the Short-Lived Access Token which can then be used to perform data i/o operations on the associated PDAs. The API call to do so is: ```javascript GET https://contracts.hubat.net/v1/contracts/keyring headers: { ‘Authorization: Bearer ’ } ``` The response to the above API call will be in JSON similar to ```javascript { "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiIsImtpZCI6IjNhMzlhZDMzLTAzNGMtNDE0Ny1hNTMwLTZmNmRlMjYyZGM1ZSJ9.eyJpc3MiOiJkYXRhc3dpZnRhZGp1ZGljYXRpb24iLCJleHAiOjE1OTMyNzkzMDQsImNvbnRyYWN0SWQiOiIyMWEzZWVkNy01ZDMyLTQ2YmEtYTg4NC0xZmRhZjcyNTk3MzAifQ.KDFqJAgrMJiKq67acaHKPZ7iRjkyxP_ZFCGZwoKX1rNMBHW5TxY7OSPkDa0bbOM7rLsmM4FrZxicUzOGErBd7nJ_T3pCj6AO3xgklkTaTiU59LLVwVktOBGk7G82EtJ5i_wy-2HqCRGOILvVmWt47Liw5tx5H0masoqVBMFZ4ZQ", "associatedHats": [ "bobtheplumber", "jillthecarpenter", "johnthebuilder", ] } ``` * The token node is the Short-Lived Access Token. \ * The associatedHots contains the PDAs that have joined the contract. * To form the fully qualified domain of the associated PDAs, append the domains hubat.net and hubofallthings.net respectively for sandbox and production environments. #### Reading and Writing Data via Contracted PDA API Both the APIs for reading and writing data via Contracted PDAs are POST commands. The API calls are made to the individual PDAs. Unlike conventional PDA data calls, the ApplicationToken is no longer required in the headers. To write data: ```javascript POST https:///api/v2.6/contract-data/create// ``` To read data: ```javascript POST https:///api/v2.6/contract-data/read// ``` * The contract namespace is defined and permitted by the Contract. It is also the namespace on the PDA where data is requested from or written to. * The data endpoint is exactly the same as how the PDA Direct Data API works. Refer to ### **The Data Body** For both the above API calls, a data body is expected. The structure of the data body is as follows: ```javascript { "token":"", "contractId":"", "hatName":"bobtheplumber", } ``` Generally speaking, the data body is the same as that of the PDA Direct Data API with the addition of 3 parameters – token, contractId and hatName. #### **Data Body for Data Writes** For **write** data, the **existing\_body** is the same as what would be posted in the PDA Direct Data API -> Create Data. For example, if the PDA Direct Data API data body is ```javascript { "something": "Normal JSON", "nested_data": { "nested": "no problem", "value": true, "id": 3 } } ``` Then the body for data creation using the Contracted PDA would be ```javascript { "token":"", "contractId":"", "hatName":"bobtheplumber", "something": "Normal JSON", "nested_data": { "nested": "no problem", "value": true, "id": 3 } } ``` #### **Data Body for Data Reads** For reading data, the original GET parameters of orderBy, ordering, skip and take are now part of the POST body. For example: ```javascript { "token":"", "contractId":"", "hatName":"bobtheplumber", "orderBy": "timestamp", "ordering": "ascending", "skip": 100 } ``` ### Exceptions The Contracted PDA API would throw the same exceptions as the Direct Data API under the same scenario, such as: * 404 thrown for invalid namespace and/or data endpoint * 403 thrown for valid but unauthorised namespace and/or data endpoint Additionally, * 403 would be thrown if the Short-Lived Access Token has expired * 403 if the Contracted PDA API is used against a PDA that has not joined the associated Contract #### **Data Body for Data Updates** To update data within a Contracted namespace the same process defined for Rich Data is used. The simplest way to start is to read the data first and use the response from the read as a starting point. If we use the following read as an example: ```javascript POST https:///api/v2.6/contract-data/read/// { "token":"", "contractId":"", "hatName":"bobtheplumber", } ``` You will get the response of the form: ```javascript [ { "endpoint": //, "recordId": "8dbaf954-c13a-46da-9c92-be3e822b6a0d", "data": { "nested_data": { "id": 11111, "value": true, "variable_string": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUz" } } } ] ``` We can update it using the following request: ```javascript PUT https:///api/v2.6/contract-data/update/ { "token":"", "contractId":"", "hatName":"", "body": [ { "endpoint": //, "recordId": "8dbaf954-c13a-46da-9c92-be3e822b6a0d", "data": { "nested_data": { "id": 22222, "value": false, "variable_string": "zUSJiOicGbhJCLiQ1VKJiOiAXe0Jye" } } } ] } ``` --- # 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/dataswyft-one-apis/contracted-pdas.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.