Connection API Details

Before an API call to a real Mydex member's PDS can be made, the connection between the member and the connecting organisation must be authenticated. The details of the authentication process can be found here. This step is not applicable if you are using the Developer Test Connection with the Sandbox server.

Dataset Types

A Mydex member's stored data foms are divided into two categories: Datasets and Transactional Datasets. The distinction between these datasets is detailed in the Data Schema.

In addition to the above datasets, there is also the Developer Namespace Dataset (only avaliable on the Sandbox server). This allows developers to save any custom serialised JSON data to a PDS. Any data can be stored in this namespace, as long as it is valid JSON. Hence, a developer can simulate storing data against a dataset that is not yet available in the Master Schema.

Return Format

The Connection API can return a response to an API request in either JSON or XML. The formats are interchangeable and are chosen by putting the desired file extension in the API request (eg. .json or .xml). In the following examples we use JSON.

Multiple Datasets

Connection API requests can be made to multiple datasets by using the + operand between datasets. For instance, a member's home details and personal details can be retrieved by using the following parameter in the API request: dataset=field_ds_home+field_ds_personal_details.

Multiple Dataset Instances

Occasionally, a member will have more than one dataset instance in their PDS (eg. multiple home addresses). In this situation, a Connection API request will return all dataset instances that the member has granted you permission to access. These datasets are identified by the key instance_N, where N is the Nth dataset instance, starting from N=0.

Note:If you add a new dataset instance to a dummy account on the Sandbox server that you wish to access via the API, you will need to regrant permission to the Developer Test Connection, selecting the datasets that you wish to share from the account.

Connection API Request Differences

The key differences when making a Connection API request for each dataset type are summarised in the table below.

Dataset Transactional Dataset Developer Namespace Dataset
About Multiple datasets with potentially multiple dataset instances Multiple datasets with potentially multiple dataset instances One dataset & dataset instance only (for any custom serialised JSON)
Availability On Production (https://api.mydex.org) & Sandbox (https://sbx-api.mydex.org) servers On Production & Sandbox servers On Sandbox server only
URL Uses the api/pds/pds path structure Uses the api/pds/transaction path structure Uses the api/pds/devnamespace path structure
When Retrieving Data The uid (345 in the following examples) is part of the path structure The uid is part of the path structure The uid is part of the path structure
The dataset instance is not included in the request The dataset instance must be included as a parameter (eg. &instance=0) The dataset instance is not included in the request
The dataset is passed as parameter The dataset is passed as parameter The dataset is not included in the request
When Updating Data The uid is part of the path structure The uid is passed as a parameter (eg. ?uid=345) The uid is part of the path structure
The dataset instance must be included in the data (eg. "0" and "1" in the following example) The dataset instance must be included as a parameter The dataset instance must be included in the data and must be "0"
The dataset must be included in the data The dataset must be included in the data and as a parameter The dataset must be included in the data
Updates are made using HTTP PUT Updates are made using HTTP POST Updates are made using HTTP PUT

In addition to the above, Connection API requests should also include the key, api_key and source_type=connection values as parameters.

Examples

Example Connection API requests for each specific dataset, and details of dataset fields can be found in the Data Schema. General examples for each dataset type can be found below.

Datasets


Retrieving Data

Example API Request

https://sbx-api.mydex.org/api/pds/pds/345.json
    ?key=YfMPI2iSFcBDQ5CdlJVQeXIbIUD156s0
    &api_key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV
    &con_id=345-1545
    &source_type=connection
    &dataset=field_ds_home

Pastable:

https://sbx-api.mydex.org/api/pds/pds/345.json?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV&api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf&con_id=345-1545&source_type=connection&dataset=field_ds_home

Example Response

{
   "field_ds_home":{
      "instance_0":{
         "field_home_street":{
            "value":"123 Fake Street",
            "access":{
               "r":{
                  "a":"1",
                  "s":"A"
               },
               "w":{
                  "a":"1",
                  "s":"A"
               }
            }
         }
      ...
      },
      "instance_1":{
         "field_home_street":{
            "value":"Viliers Street",
            "access":{
               "r":{
                  "a":"1",
                  "s":"A"
               },
               "w":{
                  "a":"1",
                  "s":"A"
               }
            }
         }
      ...
      }
   }
}

Note: only one field for each dataset instance has been included in this example to improve readability.


Updating Data

It is possible to update numerous fields in multiple dataset instances with your own data by issuing a PUT request to the Connection API.

Example API Request

As you saw in the previous example, the dummy member we created was given two field_ds_home dataset instances; one for each of his addresses. We will now submit an API request to update select details in each dataset instance.

Many browsers don't natively support PUT, so the following example uses curl to make a PUT request. This example request has been restructured to improve readability.

curl 
    -X PUT 
    -H "Content-Type: application/json" 
    -d '{
           "field_ds_home":{
              "0":{
                 "field_home_bedrooms":"2"
              },
              "1":{
                 "field_home_owner_name":"I. M. Landlord"
              }
           }
        }' 
    'https://sbx-api.mydex.org/api/pds/pds/345.json?
        key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV
        &api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf
        &con_id=345-1545
        &source_type=connection'

This request changes the field_home_bedrooms field value for the 0th dataset instance and adds the field_home_owner_name field value to the 1st dataset instance. Tables of all available datasets and details of all their fields can be found in the Data Schema.

This request can also be made via a proxy PHP script. An exapmle of how the script could be written is shown below.

<?php

$user_id = '345';

$instance[0] = 0;

$data = array();
$data['field_ds_home'][$instance[0]]['field_home_bedrooms'] = '2';
$data['field_ds_home'][$instance[0]]['field_home_owner_name'] = 'I. M. Landlord';
$data = (is_array($data)) ? http_build_query($data) : $data;

$arguments_array = array(
  'key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV',
  'api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf',
  'con_id=345-1545',
  'source_type=connection',
);
$arguments = implode('&', $arguments_array);

$mydex_api_url = "https://sbx-api.mydex.org/api/pds/pds/" . $user_id . ".json?" . $arguments;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $mydex_api_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$mydex_request = curl_exec($ch);
$mydex_request_decode = json_decode($mydex_request);

curl_close($ch);

?>

Example Response

A successful update request via PUT will return a status code of 200 OK and echo the updated fields. For example, a response to the previous example will yield:

{
   "success":1,
   "data":{
      "field_ds_home":[
         {
            "field_home_bedrooms":"2"
         },
         {
            "field_home_owner_name":"I. M. Landlord"
         }
      ]
   }
}

If unsuccessful, an error will be returned with a suggestion on how to correct the API request.


Transactional Datasets


Retrieving Data

Example API Request

https://sbx-api.mydex.org/api/pds/transaction/345.json
   ?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV
   &api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf
   &con_id=345-1545
   &source_type=connection
   &dataset=ds_browsing_history
   &instance=0

Pastable:

https://sbx-api.mydex.org/api/pds/transaction/345.json?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV&api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf&con_id=345-1545&source_type=connection&dataset=ds_browsing_history&instance=0

Example Response

{
   "1":{
      "id":"1",
      "ds_id":"1",
      "browsing_history_url":"http://www.youtube.com",
      "browsing_history_title":"YouTube",
      "browsing_history_visit_date":"1397550508"
   },
   "2":{
      "id":"2",
      "ds_id":"2",
      "browsing_history_url":"http://www.youtube.com",
      "browsing_history_title":"YouTube",
      "browsing_history_visit_date":"1397550512"
   }
}


Updating Data

The key changes when updating a transactional dataset are outlined in the table above.

Example API Request

curl 
    -X POST 
    -H "Content-Type: application/json" 
    -d '{ 
           "ds_browsing_history": {
              "browsing_history_url": "http://www.youtube.com",
              "browsing_history_title": "YouTube",
              "browsing_history_visit_date": "1397550510"
           }
        }' 
    'https://sbx-api.mydex.org/api/pds/transaction.json
        ?uid=345
        &key=YfMPI2iSFcBDQ5CdlJVQeXIbIUD156s0
        &api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf
        &con_id=345-1545
        &source_type=connection
        &dataset=ds_browsing_history
        &instance=0'

This request can also be made via a proxy PHP script. An exapmle of how the script could be written is shown below.

<?php 

$user_id = '345';

$instance[0] = 0;

$data = array();

$data['ds_browsing_history']['browsing_history_url'] = 'http://www.youtube.com';
$data['ds_browsing_history']['browsing_history_title'] = 'YouTube';
$data['ds_browsing_history']['browsing_history_visit_date'] = '1397550510';
        

$data = (is_array($data)) ? http_build_query($data) : $data;

$arguments_transactional_array = array(
  'uid=' . $user_id,
  'api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf',
  'source_type=connection',
  'con_id=345-1545',
  'key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV',
  'instance=' . $instance[0],
  'dataset=ds_browsing_history',
);
$arguments_transactional = implode('&', $arguments_transactional_array);

$mydex_api_url = "https://sbx-api.mydex.org/api/pds/transaction.json?" . $arguments_transactional;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $mydex_api_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$mydex_request = curl_exec($ch);
$mydex_request_decode = json_decode($mydex_request);

curl_close($ch);

?>

For more information on how to structure the data for transactional data sets, see the Data Schema.

Example Response

A successful update request will return a HTTP status code of 200 OK and the line {"success":1}. An unsuccessful request will return an HTTP error code and a message explaining the problem.

Developer Namespace Dataset


Retrieving Data

Example API Request

Note: There can be only one instance of the dataset, so always use instance 0 as shown in the example below.

https://sbx-api.mydex.org/api/pds/devnamespace/345.json
    ?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV
    &api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf
    &con_id=345-1545
    &source_type=connection

Pastable:

https://sbx-api.mydex.org/api/pds/devnamespace/345.json?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV&api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf&con_id=345-1545&source_type=connection

Example Response

{
   "example":"json",
   "data":{
      "something":"json"
   }
}

Updating Data

Example API Request

curl 
    -X PUT 
    -H "Content-Type: application/json" 
    -d '{
           "field_ds_developer_namespace":{
              "0":{
                 "field_dn_serialised_json":{
                    "example":"json",
                    "data":{
                       "something":"json"
                    }
                 }
              }
           }
        }'
    'https://sbx-api.mydex.org/api/pds/devnamespace/345.json
        ?key=5FXfidz9zw6YQaO2kWh0B154zz6wafrV
        &api_key=jPssYUMVVNaLaYPIbY7P9ESGzdksCOlf
        &con_id=345-1545
        &source_type=connection'

Example Response

A successful update request via PUT will return a status code of 200 OK and echo the updated fields. For example, a response to the previous example will yield:

{
   "success":1,
   "data":{
      "field_ds_developer_namespace":[
         {
            "field_dn_serialised_json":{
               "example":"json",
               "data":{
                  "something":"json"
               }
            }
         }
      ]
   }
}

If unsuccessful, an error will be returned with a suggestion on how to correct the API request.