HLA Epitope Finder REST API Endpoints

DRAFT COPY

Geoffrey H. Smith, MD
September 1, 2018
geoffrey.smith@emory.edu

Most Popular Sample Applications

1. HLA-DPB1 Allele Difference Report

2. HLA Epitope Report

Disclaimer

This project and the services it implements are for research use only.

Background

This page describes an application programming interface (API) for an HLA epitope reactivity prediction system that uses epitopes defined by the HLA Epitope Registry [1]. Compatibility predictions are based on identifying HLA Epitope Registry epitopes where all of the single antigen beads bearing the epitope are positive in a defined single antigen bead panel.

Methods

The API is implemented as a set of REpresentational State Transfer (REST) web service endpoints. Reference implementations of HTML5 web applications that use the REST API are also provided. The source code for the API and the HTML5 applications is available in GitHub (https://github.com/ghsmith/epitopeFinder). The API is implemented using Java Enterprise Edition components and is deployed on a Java Application Server. To simplify application development, the REST API maintains some state at the level of the HTTP session, but no state is durably persisted across HTTP sessions.

Resources

GET /epitopeFinder/resources/alleles

Returns a JavaScript object notation (JSON) array of HLA alleles in the IMGT database corresponding to the HLA Epitope Registry locus groups ABC (HLA-A, B, C), DRB (HLA-DRB1, 2, 3, 4, & 5), DQ (HLA-DQB1 & A1), and DP (HLA-DPB1 & A1). Only the first allele in the IMGT database corresponding to a set of synonymous alleles is returned.

Query Parameters

namerequiredtypedescriptiondefaultexample
locusGroup no String Only return alleles in the HLA Epitope Registry locus group (ABC, DRB, DQ, DP). none locusGroup=ABC
startSequenceNumber no int Alleles are sorted as they are in the IMGT database. Only alleles with a zero-based index greater than or equal to this number are returned. none startSequenceNumber=0
endSequenceNumber no int Alleles are sorted as they are in the IMGT database. Only alleles with a zero-based index less than this number are returned. none endSequenceNumber=10

Example Usage

GET /epitopeFinder/resources/alleles?startSequenceNumber=0&endSequenceNumber=10

returns JSON allele array:

allele[]
click link above

GET /epitopeFinder/resources/alleles/{alleleName}

Returns a JSON representation of the allele identified by URL parameter {alleleName}. If the allele name can't be resolved as an full IMGT allele names (e.g., HLA-A*01:01:01:01), the system will try to resolve it as an HLA Epitope Registry allele name (e.g., A*01:01).

Example Usage

GET /epitopeFinder/resources/alleles/HLA-DPB1*01:01:01:01

returns JSON allele:

allele
click link above

PUT /epitopeFinder/resources/alleles/{alleleName}

Updates the allele identified by the URL parameter {alleleName} on the server based on the JSON representation of the allele in the body of the request. The update only affects the allele in the HTTP session that is calling the method.

Modifiable Properties

nametypedescriptionexample
allele
 .recipientAntibodyForCompat
boolean If set to true, designates the allele as reactive with a recipient antibody, as a recipient type, or as a donor type and used as the basis for all of the compatibility properties (properties with names starting with compat). The following properties are automatically recomputed for all alleles and epitopes based on the values of the various ...ForCompat properties:
  • allele.compatEpRegEpitopeMap
  • allele.compatInterpretation
  • epRegEpitope.alleleMap{}.compatStatus
  • epRegEpitope.compatAlleleFilterMap{}
  • epRegEpitope.compatSabPanelCountPresent
  • epRegEpitope.compatSabPanelCountAbsent
  • epRegEpitope.compatSabPanelCountUnknown
  • epRegEpitope.compatSabPanelPctPresent
{...
recipientAntibodyForCompat: true,
...}
allele
 .recipientTypeForCompat
boolean {...
recipientTypeForCompat: true,
...}
allele
 .donorTypeForCompat
boolean {...
donorTypeForCompat: true,
...}

GET /epitopeFinder/resources/epRegEpitopes

Returns a JSON array of HLA Epitope Registry epitopes.

Query Parameters

namerequiredtypedescriptiondefaultexample
panelAllelesOnly no boolean Only return alleles associated with the epitope that are part of a single antigen bead panel. false panelAllelesOnly=true
startSequenceNumber no int Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than or equal to this number are returned. none startSequenceNumber=0
endSequenceNumber no int Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than this number are returned. none endSequenceNumber=10

Example Usage

GET /epitopeFinder/resources/epRegEpitopes?panelAllelesOnly=true&startSequenceNumber=0&endSequenceNumber=10

returns JSON epitope array:

epRegEpitope[]
click link above

GET /epitopeFinder/resources/epRegEpitopes/{locusGroup}

Returns a JSON array of HLA Epitope Registry epitopes in the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) identified by the URL parameter {locusGroup}.

Query Parameters

namerequiredtypedescriptiondefaultexample
panelAllelesOnly no boolean Only return alleles associated with the epitope that are part of a single antigen bead panel. false panelAllelesOnly=true
startSequenceNumber no int Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than or equal to this number are returned. none startSequenceNumber=0
endSequenceNumber no int Epitopes are sorted as they are in the HLA Epitope Registry database. Only epitopes with a zero-based index greater than this number are returned. none endSequenceNumber=10

Example Usage

GET /epitopeFinder/resources/epRegEpitopes/ABC?panelAllelesOnly=true&startSequenceNumber=0&endSequenceNumber=10

returns JSON epitope array:

epRegEpitope[]
click link above

GET /epitopeFinder/resources/epRegEpitopes/{locusGroup}/{epitopeName}

Returns a JSON HLA Epitope Registry epitope identified by the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) {locusGroup} and the epitope name {epitopeName}.

Query Parameters

namerequiredtypedescriptiondefaultexample
panelAllelesOnly no boolean Only return alleles associated with the epitope that are part of a single antigen bead panel. false panelAllelesOnly=true

Example Usage

GET /epitopeFinder/resources/epRegEpitopes/ABC/62GE?panelAllelesOnly=true

returns JSON epitope:

epRegEpitope
click link above

GET /epitopeFinder/resources/sabPanels

Returns a JSON array of single antigen bead panels representing the currently active panels. Currently, these panels are administratively specified, although in a more complete implementation the API will allow the panels to be specified by the client.

Example Usage

GET /epitopeFinder/resources/sabPanels

returns JSON single antigen bead panel array:

sabPanel[]
click link above

GET /epitopeFinder/resources/sabPanels/{locusGroup}

Returns a JSON representation of the single antigen bead panel identified by the HLA Epitope Registry locus group (ABC, DRB, DQ, DP) {locusGroup}.

Example Usage

GET /epitopeFinder/resources/sabPanels/ABC

returns JSON single antigen bead panel:

sabPanel
click link above

GET /epitopeFinder/session

Returns a JSON representation of the current session ID. All changes (e.g., clinical information such as antibody profile) are persisted in the session and are disposed of when the session ends. Sessions automatically time out after 30 minutes. This method takes no parameters.

Example Usage

GET /epitopeFinder/resources/session

returns JSON sessionId:

sessionId
click link above

PUT /epitopeFinder/session/reset

End the current session. All changes are immediately disposed. This request has no payload.

Reference Implementations of Applications that use the REST API

These applications demonstrate how the HLA Epitope Finder REST API may be used to prognosticate about HLA donor/recipient compatibility. They are presented in order of increasing complexity. Although these applications have some utility in their own right, they are mainly intended to serve as a guide to software engineers seeking to use the HLA Epitope Finder REST API in a larger system, such as in a specialty HLA laboratory information system or in a clinical decision support module of an electronic medical record system.

HLA Epitope Report

This report shows the single antigen beads associated with recipient epitopes and characterizes them as present (positive), absent (negative), or unknown (not in the current single antigen bead panel).

Source code: https://github.com/ghsmith/epitopeFinder/blob/master/epitopeFinder-webServices/src/main/webapp/ajaxEpitopeReport.html

HLA Epitope Compatibility Report

This report makes donor/recipient compatibility predictions based on inferred antibody reactivity to epitopes.

Source code: https://github.com/ghsmith/epitopeFinder/blob/master/epitopeFinder-webServices/src/main/webapp/ajaxCompatibilityReport.html

HLA Epitope Compatibility Report ⟹ Express ⟹

Same as above, but without epitopes. This version works better on devices that have smaller displays, limited bandwidth, or slower graphics rendering.

Source code: https://github.com/ghsmith/epitopeFinder/blob/master/epitopeFinder-webServices/src/main/webapp/ajaxCompatibilityReportNoEpitopes.html

References

[1] Duquesnoy, R. J., Marrari, M., Mulder, A., L. C. D. Da Mata Sousa, Silva, A. S., & Monte, S. J. (2014). First report on the antibody verification of HLA-ABC epitopes recorded in the website-based HLA Epitope Registry. Tissue Antigens, 83(6), 391-400.


Copyright © 2018, Geoffrey H. Smith, MD