Using the iReceptor Web API

The iReceptor Repository Service implements the AIRR Community's MiAIRR data sharing recommendations, using a REST API to perform queries against a AIRR repository and responding to that query with a well defined JSON response. The definition of the iReceptor API is available at the iReceptor API GitHub Repository. The API has two main entry points, one for metadata at the study/subject/sample level and one for the annotated sequence level of AIRR-seq data. These API entry points are:

For those repositories that support the iReceptor security layer, the following information is required to connect to an iReceptor Repository Service:

  • client_name: the username that creates the trust relationship between the iReceptor Gateway and the Repository Service. This prevents untrusted servers from connecting to the repository. This username/secret pair would typically be provided to the client by the repository data steward. For a repository to be used by the iReceptor Gateway a repository must provide this information to the iReceptor Gateway when the repository is registered with iReceptor.
  • client_sharedsecret: the shared secret or "password" required to connect to the repository service as a trusted consumer of data.
  • dbservice.host.org: the hostname and base URL for the entry point for repository connections. The base URL allows multiple versions of the API to be supported on the same server.
  • dbusername: the username for accessing the data repository itself. This allows the repository to provide a second layer of user level authorization to the repository.

For example, if a client_name:client_sharedsecret is provided to an application such as iReceptor (e.g. ireceptor:ireceptorsecret), then iReceptor would send that information to the repository service as above. The service can then confirm that the client is how they say they are. In addition, the iReceptor Gateway would send the user identity of the individual on the gateway making the request to the repository service. This allows a data steward to control access at the user level as well as the client level. Note at this time no user level authentication is performed, so user level access is based on a trust relationship between the client (using the client_name and sharedsecret) and the repository. That is, in the example above, the repository and the gateway share a mapping of the username and the repository trusts that the client is managing access to user's.For those repositories that implement the above security protocol, Nit is not possible to access an iReceptor Repository Service unless the consumer of the service is provided with a valid client_username and client_sharedsecret. Thus when using URLs of the form above, access will be denied unless the correct authentication mechanisms are used.It is not necessary for all repositories to implement the iReceptor security protocol. In this instance, the repository is providing public, open data to the iReceptor Data Commons. In these instances, simple URLs such as:

iReceptor manages the iReceptor Public Archive (IPA), using Compute Canada resources, using URLs of the form https://ipa1.ireceptor.org. This repository is running the iReceptor v2.0 version of the iReceptor IPA. As such, it is possible to retrieve data using the following URLs: