Web API Overview

This article describes the resources that make up the official Huron IRB Exchange API. If you have any problems or requests, please contact support.

  1. Parameters
  2. Root Endpoint
  3. Client Errors
  4. HTTP Verbs
  5. Authentication
  6. Authorization
  7. Request Headers
  8. Cross Origin Resource Sharing
  9. Upload Limits

Parameters

Some API methods take optional parameters. For GET requests, any parameter not specified as a segment in the path can be passed as an HTTP query string parameter:

GET https://api.huronirbexchange.com/containers/5ef5550c5d7647efa997b5700c072f7b/items?since=2017-05-16

In this example, the 5ef5550c5d7647efa997b5700c072f7b value is provided for the :container parameter in the path while :since is passed in the query string.

For POST, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json' and sent in the body of the request.

Root Endpoint

You can issue a GET request to the root endpoint to get all the endpoints that the API supports:

GET https://api.huronirbexchange.com
GET https://test-api.huronirbexchange.com

Client Errors

Unfortunately, every request will not be successful. When a failure does occur, the IRB Exchange will respond with the following error format:

{
    "code": 1006,    
    "status": 400,  
    "message": "A required field is missing.", 
    "details": "Please supply a value for 'name' that conforms to the API specification."
}
NameDescription
codeThe IRB Exchange-specific error code
statusThe HTTP status code
messageThe message specific to the error code
detailsThe message containing details about the specific occurence of the error

The IRB Exchange defines a number of distinct error codes to let you know what is wrong. For specific information about an error, please refer to the error codes.

HTTP Verbs

Where possible, the IRB Exchange API strives to use appropriate HTTP verbs for each action.

VerbDescription
GETUsed for retrieving resources
POSTUsed for creating resources
PUTUsed for replacing/updating resources
DELETEUsed for deleting resources

Authentication

All requests made to the IRB Exchange require authentication. Failure to send authentication information in a request will cause IRB Exchange API to return 404 No Found. This is to prevent the accidental leakage of private information to unauthorized users.

The IRB Exchange uses a custom Authentication scheme that uses X.509 certificates to validate the originator of each request. Each inbound request into the IRB Exchange API must contain a unique signature that can be verified using the public key of the organization making the request.

See the section on request signing for specific details on how to construct a valid request signature.

Authorization

The IRB Exchange API provides two levels of authorization that are determined at the time of registration.

Single IRB of Record - (sIRB)

Institutions may register with Huron Consulting Group to have an sIRB account created. When registered as an sIRB, an organization is allowed to create new containers within the system, and they can grant access to any other organization within the IRB Exchange system for collaboration.

Participating Site - (pSite)

Institutions may register with Huron Consulting Group at no cost to have a pSite account created. When registered as a pSite, an institution may collaborate on studies to which they have been invited by an sIRB organization. pSite accounts are not allowed to create new containers or invite other organizations to collaborate. pSite accounts are allowed to add study-related information to the containers that they have been invited to collaborate on.

Request Headers

User Agent Header

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. We request that you use the name of your application for the User-Agent header value. This allows us to contact you if there are problems.

Example:

User-Agent: MyClientApplication/1.2.3

Request Id Header

All API requests MUST include a valid Huron-IrbX-Request-Id header. Requests with no Huron-IrbX-Request-Id header will be rejected. We request that you use a universally unique identifier. This is helpful for tracking requests through each system. The Huron-IrbX-Request-Id header will be included in the HTTP response, so that you can correlate the request and response in your system logs.

Example:

Huron-IrbX-Request-Id: 7231e51e-2b86-4d64-a070-6614ae775254

Host Header

All API requests MUST include a valid Host header. Requests without a Host header will be rejected. The IRB Exchange API will validate the value against the host of the IRB Exchange API. If the values are not the same, the request will be rejected.

Example:

Host: api.huronirbexchange.com

Date Header

All API requests MUST include a valid Huron-IrbX-Date header. Requests without a Date header will be rejected. The IRB Exchange API uses a variant of the ISO 8601 format that does not include hyphens - between date parts and does not include colons : betwen time parts. Accuracy to the second is all that is necessary for the header value. The date value should be converted to Universal Coordinated Time (UTC) prior to formatting.

The format for the header value: yyyyMMddThhmmssZ

Date partDescription
yyyyThe 4-digit year
MMThe 2-digit month
ddThe 2-digit day of the month
TThe literal character 'T'
hhThe 2-digit hour from the 24 hour clock
mmThe 2-digit minutes
ssThe 2-digit seconds
ZThe literal character 'Z'

Example:

Huron-IrbX-Date: 20170516T114638Z

Cross Origin Resource Sharing

The API support Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

Upload Limits

All requests must be less than or equal to 300 mebibytes. Larger requests will be rejected.