Data Debit
The standard approach is for applications to have access to a single designated namespace. It is however possible to have data access to other unrelated namespaces
. This can be achieved through a domain-specific data debit
mechanism. By default, all applications have read-and-write access to the namespace
specified upon creation but if for example, the application needs to read users' Facebook posts, then a data debit
will have to be created by the application developer and be accepted by the users.
For example, the Notables
application has a data debit
to fetch and display the PDA profile information.
Data debit
confirmation process is incorporated into the application's Permission Contract request and agreement screen that details which application can access what data. Users have to agree in order for the application
or Data Plug
to function as intended.
The more general process of creating a Data Debit is:
Propose a Data Debit specification to a PDS
The server owner sees the Data Debit as a pending request, reviews and approves it by confirming it or rejects it.
Dataswift's platform will log the contract and the Data Debit becomes enabled.
The general process of getting the values from a Data Debit is:
Request Data Debit values from the PDS
Optional: If any changes are required to the Data Debit request, submit a request to update it
Data debit proposal
The first step in retrieving private data from a PDA is to submit a Data Debit request – POST /api/v2.6/data-debit/$dataDebitKey
. Where dataDebitKey
can be any valid URL path, however it needs to be unique on the PDS. The request will fail otherwise.
The general schema of a Data Debit is:
As a concrete example, the below request asks for user profile together with location data.
If your request is valid and hence accepted by the PDA, the response will be 201 CREATED
status, with the full specification of the data debit
in the request body. Please note that both the Data Debit ID and the Bundle name must be unique – Data Debit key identifies the relationship between the user and an application, while the Bundle name identifies the specific data being exchanged. The request will fail otherwise.
Approve Data Debit
An application developer is not authorised to approve data debits, this is managed using an API call: GET /api/v2.6/data-debit/$dataDebitKey/enable
. Where $dataDebitKey
can be any valid URL path; however it needs to be unique on the PDA, and $bundleName
can be any valid name. Specifically, it requires both the Data Debit key
and the bundle name
to be set to accurately identify the data that is being shared.
Request Data Debit Values
Once a Data Debit has been both proposed and approved by the PDA owner, it is achieved with a simple GET /api/v2.6/data-debit/$dataDebitKey/values
request. Where $dataDebitKey
can be any valid URL path; however it needs to be unique on the PDA.
If the data debit is enabled, the response is exactly the same as if you were using Data Bundles directly:
If, on the other hand, you try to request data from a Data Debit that has not been enabled, you will receive an error:
That's it! You have now successfully received data from a PDA owner using a Data Debit agreement.
Update data debit
Data requirements may change over time. It may be required to update an existing Data Debit. There are two solutions to this problem:
Request a new Data Debit with the updated requirements
Update an existing Data Debit
Updating an existing data debit
has the benefit of building on an existing relationship with the PDA owner: they see the scope of your request increasing, however they will recognise your application as one they have already agreed to share data with. The request for updating an existing data debit
is: PUT /api/v2.6/data-debit/$dataDebitKey
. Where $dataDebitKey
can be any valid URL path, however it needs to be unique on the PDS.
The example below requests 10 recent profile records, up from 1 in the previous example:
Last updated