ADS 2.0 REST API

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

About

This is new, simple REST API used for server-to-server communication to the Attribute Data Service 2.0, to allow owners of specific apps in the ADS to query data contained in those apps. The goal of this API is to allow easy access to the data for web developer, regardless of technology.

API

Requests

Request URL

The requests are done using a URL constructed as follows: (scheme)(base API URL)/(API version)/(app ID)/(query)
Where:

• scheme: Only https:// is allowed.
• base API URL: the base API url for a particular ADS instance, such as api.pdsoperator.org
• version: the version number for the API. An ADS may add functionality to the API without updating the version, but for any breaking change, the version will be updated, and the older version maintained so that developers have time to migrate their code to the new version.
• app ID: the ID for a specific app running in the ADS, such as rbmw for the Royal Borough of Maidenhead and Windsor app. The app ID will be specified by the operator of the ADS when that app is added to the ADS.
• query: this is covered in detail later

 Example: https://boston1.azigo.net/v1/rbwm.gov.uk/users/profile/testUser
 REST API demo page: http://boston1.azigo.net/v1/samples/demo.html

Request Headers

• Authorization: Required. The operator of the ADS will issue an API key that allow an app owner to access data in that app, but not any other data in the ADS. Put your API key in the authorization header. Example: 98ea3b193ed2fa804ebbef4fb2391cac.

• Content-Type: Optional. Tells the ADS what serialization format to use. If not specified, JSON is used by default. Allowable values are json/txt, application/xml, text/n3, etc. Only JSON and XML are already implemented.

Request Methods

• GET is supported for reading
• POST is supported for updating
• PUT and DEL are not supported
  

Pagination

For queries that could potentially have a very large response (say, list all users in an app), the response should be paginated. Page size TBD, maybe 1,000?

• /users -> Returns the first page of a paginated list of user IDs, or all IDs if the total number is less than the page size.
• /users?page=3 -> Returns page 3 of the list of user IDs

<response page="3" nextPage="4">
  <user_id="a1234567">
  ...
  <user_id="a1234569">
</response>

• /users?since=yesterday --> Returns list of users modified since the indicated time. Accepts unix timestamp or relative timestamp formats

Queries

• GET /meta -> Returns some metadata about the app (TBD, possibly output dtd, xsd, owl, mapping, etc.)
• GET /users
  
• GET /users/profile/a12345678 -> Returns the complete profile of the user ID a12345678. If the app has a mapping context, the attributes are identified by the remote identifiers instead of the persona.owl identifiers.

XML encoded:

<?xml version="1.0" encoding="UTF-8"?>
  <Profile uid="a1234567">
    <f_name>Paul</f_name>
    <l_name>Trevithick</l_name>
    <gender>Male</gender>
    <address>
      <Address>
        <type>work</type>
        <org>Azigo, Inc.</org>
        <street1>30 Washington Street</street1>
        <city>Wellesley</city>
        <state>MA</state>
        <zip>02481</zip>
      </Address>
    </address>
  </Profile>

JSON encoded:

{Profile:{firstName:Jhon,
          phone:[111,222],
          multiValuedAddress:[{Address:{zipCode:33333}},{Address:{zipCode:44444}}], 
          singleValuedAddress:{Address:{zipCode:W1H 5LR,town:London}}}}

• POST /users/profile/a12345678 -> Updates the user record of the user ID a12345678. The payload of the POST contains the data to be updated/added/deleted. If the app has a mapping context, the attributes can be identified by the remote identifiers instead of the persona.owl identifiers. Example:

POST /users/profile/a12345678 HTTP/1.1
Content-Type: application/xml
Authorization: Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=
<?xml version="1.0"?>
  <user>
    <email>Bob@rob.com</email>
  </user>

Responses

HTTP Status code - Description

• 200 OK - Request processed successfully.
• 400 Bad Request - Invalid identifier or query parameter
• 401 Unauthorized - API key was not provided or is invalid.
• 403 Forbidden - Your API key does not allow access to the particular resource requested
• 404 Not Found - Query with valid parameters returned no data
• 500 Internal Server Error - There was an unexpected error on our server.

Note: This list does not cover all possible HTTP Status Codes that could be returned, only those returned specifically from our API. For example, if the request cannot make it to our API you will likely get a "503 Service Unavailable" response. With this in mind, do not code exclusively to handle the response codes listed above.

See Also

Higgins PDS Access