Your first request to the Mydex PDS API

If you've been following along with the 'Getting Started' guide, by now you will have:

We will now take a look at a few example PDS API requests between a PDS and organisation.


Example PDS API Requests

As an example, we'll be examining how to access a PDS on the sandbox. In this case, we have decided to name the test subject member 'Mr Robert Fish'.

Querying a PDS

If we wanted to request Robert's home address, we'd make an HTTP GET request that looks a bit like this:

https://sbx-api.mydex.org/api/pds/pds/97.json
    ?api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0
    &key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA
    &con_id=97-1545
    &source_type=connection
    &dataset=field_ds_home

When we make this call, we'll be connecting to Robert's PDS, which has a uid of 97. We send our api_key to identify ourselves and we also send our connection key. This key isn't stored by Mydex - only the connecting organisation and the owner of the PDS have a copy of this key.

Because we want Robert's home address, we're also requesting the home dataset, field_ds_home. Because we're connecting on behalf of our company DemoCorp, we're sending along our connection id (con_id).

In return, you will receive an instance of Robert's Home dataset, represented in JSON.

Try it Yourself

You can try a concrete example here by pasting this url into a browser, an HTTP client like Postman, or a command line tool such as curl.

Although here we have shared a connection key and api_key, this is for demonstrative purposes only and your own information should be kept private.

Example

Fetch Robert's Address as JSON

https://sbx-api.mydex.org/api/pds/pds/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=field_ds_home

Understanding the Response

Information in a Mydex PDS exists as a series of datasets. If you tried making the request above, you should see a response showing an instance of Robert's Home dataset, represented in JSON.

The response should look something like the JSON below, slightly edited for brevity:

json { "field_ds_home": { "instance_0": { "field_home_country": { "value": "UNITED KINGDOM", "access": {…} } }, "field_home_county": { "value": "Lincolnshire", "access": {…} } }, "field_home_postcode": { "value": "DN216BY", "access": {…} }, "field_home_property_type": { "value": "House", "access": {…} }, "field_home_street": { "value": "Viliers Street", "access": {…} } }, "field_home_town": { "value": "Gainsborough ", "access": {…} } } } } }

Fetching different datasets

So far we've fetched information about Robert's home, but we can fetch other information too. Because we have added the Developer Connection to this dummy account, sharing is automatically permitted for all information.

Examples

Other datasets can be retrieved by changing the dataset parameter in the request. For example, personal details can be accessed by changing dataset=field_ds_home to dataset=field_ds_personal_details.

Fetch Robert's personal details as JSON


https://sbx-api.mydex.org/api/pds/pds/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=field_ds_personal_details


Fetch Robert's home details as JSON

https://sbx-api.mydex.org/api/pds/pds/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=field_ds_home


Fetch Robert's driving licence details as JSON

https://sbx-api.mydex.org/api/pds/pds/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=field_ds_driving_licence


Fetch Robert's itemised phone call list as JSON

https://sbx-api.mydex.org/api/pds/transaction/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=ds_utility_tel_calls&instance=0


Fetch Robert's browsing history as JSON

https://sbx-api.mydex.org/api/pds/transaction/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=ds_browsing_history&instance=0


Fetch Robert's bank transactions as JSON

https://sbx-api.mydex.org/api/pds/transaction/97.json?key=ZUiaOt3g6mBk0GQL2mx45uMLu4DG82VA&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-1545&source_type=connection&dataset=ds_bank_account_transactions&instance=0

A list of all available datasets can be found in the Data Schema.


Your Own API Request

You can see how this all looks with your own API key and the PDS you have created by following these steps:

  1. Sign in to you PDS on the Sandbox.
  2. Click on the 'Connections' tab on the left.
  3. If necessary, select 'Mydex Developer Test Connection'
  4. Click on 'Developer Information' to expand the section.

Updating a sandbox PDS

Here you can see all the connection details between you and this sandbox PDS. There is a code snippet which illustrates how these details are passed as parameters when making a PDS API request. Replace the YOUR-API-KEY part with your API key from your developer account and paste the URL into a browser. Alternatively, use a tool such as curl to retrieve the data.

A successful API request will send back a JSON representation of your PDS's data, similar in structure to the examples above.


Further Reading

If you have been following along, at this stage you have now learned the basics of the PDS API.

For further reading please click on the links below. These cover the authentication process for the Connection API, as well as more advanced functionality, such as how to update a member's PDS with your data and the Developer Namespace Dataset.

There is also a data schema listing all the datasets you can connect to using the API.

PDS API overview
API Authentication Process
Using the PDS API
PDS Data Schema