Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ADS 2.0 REST API"

(Request Headers)
(Request Headers)
Line 25: Line 25:
 
*Authorization: Required. The operator of the PDS will issue an API key that allow an app owner to access data in that app, but not any other data in the PDS. Put your API key in the authorization header. Example: 98ea3b193ed2fa804ebbef4fb2391cac.
 
*Authorization: Required. The operator of the PDS will issue an API key that allow an app owner to access data in that app, but not any other data in the PDS. Put your API key in the authorization header. Example: 98ea3b193ed2fa804ebbef4fb2391cac.
  
*Content-Type: optional. Tells the PDS what serialization format to use. If not specified, JSON (json/txt) is used by default. Allowable values are json/txt, application/xml, text/n3, etc. JSON and XML are already implemented.
+
*Content-Type: Optional. Tells the PDS what serialization format to use. If not specified, JSON (json/txt) is used by default. Allowable values are json/txt, application/xml, text/n3, etc. JSON and XML are already implemented.
  
 
==== <br>Request Methods<br>  ====
 
==== <br>Request Methods<br>  ====

Revision as of 10:06, 16 November 2010

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

About

This is a proposed simple REST API used for server-to-server communication to the PDS, to allow owners of specific apps in the PDS 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 PDS instance, such as api.pdsoperator.org
  • version: the version number for the API. A PDS 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 PDS, such as rbmw for the Royal Borough of Maidenhead and Windsor app. The app ID will be specified by the operator of the PDS when that app is added to the PDS.
  • query: this is covered in detail later


Example: https://boston1.azigo.net/v1/rbwm.gov.uk/users/profile/testUser

Request Headers

  • Authorization: Required. The operator of the PDS will issue an API key that allow an app owner to access data in that app, but not any other data in the PDS. Put your API key in the authorization header. Example: 98ea3b193ed2fa804ebbef4fb2391cac.
  • Content-Type: Optional. Tells the PDS what serialization format to use. If not specified, JSON (json/txt) is used by default. Allowable values are json/txt, application/xml, text/n3, etc. 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

Input/Output Format

Tells the PDS what serialization format to use. This parameter is optional, if not specified JSON is default. Allowable values are json, xml, n3.

  • /users?output=json -> Returns the list of users in JSON format.
  • /users?output=n3 --> Returns the list of users in RDF N3 format.


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

Back to the top