Your first request to the Mydex Connection 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 Connection API requests between a dummy member and organisation.


Example Connection API Requests

As an example, we'll be examining how to access the PDS of our own dummy member account. In this case, we have decided to name the test subject member 'Mr Robert Fish'.

Because this is an account we have set up on the Sandbox PDS server, this API call will be made to the Sandbox API server https://sbx-api.mydex.org. API requests to genuine members on https://pds.mydex.org are given to the normal API server, https://api.mydex.org.

Querying a Member's 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=HpFE4osh84cOn7BdYR7T24Eyf4vQB48i
    &con_id=97-2156
    &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 encryption key, used to decrypt the data in the PDS that we have access to. This key isn't stored by Mydex - only the connecting organisation and the owner of the PDS have a copy of this key. After it is used to decrypt data during a request, it is deleted from Mydex's servers.

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 an encyption 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=HpFE4osh84cOn7BdYR7T24Eyf4vQB48i&api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0&con_id=97-2156&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:

    {
        "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 (For a real PDS, it is up to the member to grant the connecting organisation access permission).

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=HpFE4osh84cOn7BdYR7T24Eyf4vQB48i
    &api_key=fnQIXC1zOvPgRYy993R7kiUq30slomY0
    &con_id=97-2156
    &source_type=connection
    &dataset=field_ds_personal_details

Pastable:

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

Fetch Robert's driving licence details as JSON

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

Pastable:

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

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 dummy member account you have created by following these steps:

  1. Sign in to the dummy account on the Sandbox Server.
  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 dummy member. There is a code snippet which illustrates how these details are passed as parameters when making a Connection 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 dummy member'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 Connection API.

For further reading plase 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.

Connection API overview
API Authentication Process
Connection API Details
Data Schema