HLA-DPB1 REST API Endpoints

DRAFT COPY

Geoffrey H. Smith, MD
August 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-DPB1 allele compatibility prediction system. Compatibility predictions are based on considering recipient antibody reactivity to epitopes at six (6) hypervariable regions in the DPB1 protein [1-4].

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/hladpb1). 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 /hladpb1/resources/alleles

Returns a JavaScript object notation (JSON) array of HLA-DPB1 alleles. Some filtering is supported using query parameters. Only codons 1-100 are returned.

Query Parameters

namerequiredtypedescriptiondefaultexample
synonymous no boolean If set to false, only the longest protein sequence allele of sets of synonymous alleles is returned. Allele order is based on the IMGT database. true (i.e., no filtering) synonymous=false
sab no boolean If set to true, only alleles associated with single antigen beads (SAB) are returned. false (i.e., no filtering) sab=true
hvrMatchCount no int If specified, only alleles with at least this many hypervariable regions matching the refeference allele are returned. 0 (i.e., no filtering) hvrMatchCount=4
noCodons no boolean If set to true, codons are not returned, which substantially reduces the JSON payload size. false noCodons=true

Example Usage

GET /hladpb1/resources/alleles?synonymous=false&sab=true&hvrMatchCount=3

returns JSON allele array:

allele[]
click link above

GET /hladpb1/resources/alleles/{alleleName}

Returns a JSON representation of the allele identified by URL parameter {alleleName}. Only codons 1-100 are returned.

Query Parameters

namerequiredtypedescriptiondefaultexample
noCodons no boolean If set to true, codons are not returned, which substantially reduces the JSON payload size. false noCodons=true

Example Usage

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

returns JSON allele:

allele
click link above

PUT /hladpb1/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. This is intended to allow clients to update a limited number of clinically determined allele and hypervariable region properties related to an HLA-DPB1 compatibility evaluation. A JSON representation of an allele is presented in the previous example usage. A JSON representation of a hypervariable region is presented in the subsequent example usage. This method has no output.

Query Parameters

namerequiredtypedescriptiondefaultexample
enumeratedAlleleMode no boolean If set to true, use the enumerated allele properties (donorAlle1, donorAllele2, recipientAllele1, and recipientAllele2) and allow the system to automatically set donorTypeForCompat and recipientTypeForCompat for the compatiblity evaluation. When an enumerated allele property is set for an allele, it is automatically unset for all other alleles. This is intended for use by clients that maintain a distinction between recipient allele #1 and #2 and donor allele #1 and #2. Clients that don't care about this distinction should not use the enumeratedAlleleMode query parameter and just use the donorTypeForCompat and recipientTypeForCompat properties, which are usually easier to work with. false enumeratedAlleleMode=true

Modifiable Properties

nametypedescriptionexample
allele
 .referenceForMatches
boolean If set to true, this is the reference allele for all hypervariable region match properties (properties with names starting with matches). When this property is set for an allele, the property is unset for any other allele (i.e., there can only be one reference allele) and the following properties are automatically recomputed for all alleles:
  • allele.matchesHvrCount
  • allele.hvrVariantMap{}.matchesReference
  • allele.codonMap{}.matchesReference
{...
referenceForMatches: true,
...}
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). When any of these properties are set for an allele, the following properties are automatically recomputed for all alleles and hypervariable region variants:
  • allele.compatInterpretation
  • hypervariableRegion.variantMap{}.compatIsRecipientEptiope
  • hypervariableRegion.variantMap{}.compatPositiveSabCount
  • hypervariableRegion.variantMap{}.compatAntibodyConsideredPresent
  • hypervariableRegion.variantMap{}.beadAlleleRefList{}.compatBeadPositive
{...
recipientAntibodyForCompat: true,
...}
allele
 .recipientTypeForCompat
boolean {...
recipientTypeForCompat: true,
...}
allele
 .donorTypeForCompat
boolean {...
donorTypeForCompat: true,
...}
allele
 .recipientAllele1
boolean The enumerated recipient and donor allele properties are only provided for the convenience of clients that need to keep track of which allele represents allele #1 and which allele represents allele #2. When one of these properties is set for an allele, it is concurrently unset for all other alleles (i.e., there can only be one allele #1 and one allele #2). {...
recipientAllele1: true,
...}
allele
 .recipientAllele2
boolean {...
recipientAllele2: true,
...}
allele
 .donorAllele1
boolean {...
donorAllele1: true,
...}
allele
 .donorAllele2
boolean {...
donorAllele2: true,
...}

GET /hladpb1/resources/hypervariableRegions

Returns a JavaScript object notation (JSON) array of HLA-DPB1 hypervariable regions. This method takes no parameters

Example Usage

GET /hladpb1/resources/hypervariableRegions

returns JSON hypervariableRegion array:

hypervariableRegion[]
click link above

GET /hladpb1/resources/hypervariableRegions/{hypervariableRegionName}

Returns a JSON representation of the hypervariable region identified by URL parameter {hypervariableRegionName}. This method takes no parameters.

Example Usage

GET /hladpb1/resources/hypervariableRegions/f

returns JSON hypervariableRegion array:

hypervariableRegion
click link above

PUT /hladpb1/resources/hypervariableRegion/{hypervariableRegionName}

Updates the hypervariable region identified by the URL parameter {hypervariableRegionName} on the server based on the JSON representation of the hypervariableRegion in the body of the request. The update only affects the hypervariable region in the HTTP session that is calling the method. This is intended to allow clients to update a limited number of clinically determined allele and hypervariable region properties related to an HLA-DPB1 compatibility evaluation. A JSON representation of a hypervariable region is presented in the previous example usage. A JSON representation of an allele is presented in the GET /hladpb1/resources/alleles/{alleleName} section. This method takes no parameters and has no output.

Modifiable Properties

nametypedescriptionexample
hypervariableRegion
 .variantMap{}
  .knownReactiveEpitopeForCompat
boolean If set to true, the recipient is assumed to have an antibody reactive with the epitope regardless of all other considerations and used as a basis for all of the compatibility properties (properties with names starting with compat). When this property is set for a hypervariable region variant, the following properties are automatically recomputed for all alleles and hypervariable region variants:
  • allele.compatInterpretation
  • hypervariableRegion.variantMap{}.compatIsRecipientEptiope
  • hypervariableRegion.variantMap{}.compatPositiveSabCount
  • hypervariableRegion.variantMap{}.compatAntibodyConsideredPresent
  • hypervariableRegion.variantMap{}.beadAlleleRefList{}.compatBeadPositive
{...
knownReactiveEpitopeForCompat: true,
...}

GET /hladpb1/resources/hypervariableRegions/reagentLotNumber

Returns a JSON representation of the current single antigen bead reagent lot number (each hypervariable region variant is associated with a set of single antigen beads). The reagent lot number is currently administratively specified. This method takes no parameters.

Example Usage

GET /hladpb1/resources/hypervariableRegions/reagentLotNumber

returns JSON reagentLotNumber:

reagentLotNumber
click link above

GET /hladpb1/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 /hladpb1/resources/session

returns JSON sessionId:

sessionId
click link above

PUT /hladpb1/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-DPB1 REST API may be used to prognosticate about HLA-DPB1 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-DPB1 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-DPB1 Allele Difference Report (AJAX - uses REST API)

For a given HLA-DPB1 reference allele, this highly interactive report sorts all other HLA-DPB1 alleles from most similar to least similar based on hypervariable region epitopes. This is the most basic usage of the HLA-DPB1 REST API. The report is implemented as an HTML5 web page that uses the jQuery asynchronous JavaScript and XML (AJAX) API to access the HLA-DPB1 REST endpoints described above.

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

HLA-DPB1 Allele Difference Report ⟹ Express ⟹

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

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

HLA-DPB1 Compatibility Report

This highly interactive report makes donor/recipient compatibility predictions based on the donor/recipient HLA-DPB1 types and the recipient antibody profile (SAB positivity and/or known reactivity to particular hypervarible epitopes). The report is implemented as a single HTML5 web application that uses the jQuery AJAX API to access the HLA-DPB1 REST endpoints.

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

HLA-DPB1 Compatibility Report ⟹ Express ⟹

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

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

HLA-DPB1 Compatibility Wizard

This wizard makes donor/recipient compatibility predictions based on the donor/recipient HLA-DPB1 types and the recipient antibody profile (SAB positivity and/or known reactivity to particular hypervarible epitopes). The wizard is implemented as a static HTML5 web page that uses the jQuery AJAX API to access the HLA-DPB1 REST endpoints and jQuery Mobile user interface components.

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

References

[1] Billen, E. V., Christiaans, M. H., Doxiadis, I. I., Voorter, C. E., & Berg-Loonen, E. M. (2010). HLA-DP antibodies before and after renal transplantation. Tissue Antigens, 75(3), 278-285.

[2] Piazza, A., Poggi, E., Ozzella, G., Borrelli, L., Scornajenghi, K., Monaco, P., Tisone, G., & Adorno, D. (2006). Anti Hla-Dp Antibodies And Graft Failure In Kidney Transplantation. Transplantation, 82(Suppl 2), 242.

[3] Arnold, M., Pei, R., Spriewald, B., & Wassmuth, R. (2005). Anti-HLA class II antibodies in kidney retransplant patients. Tissue Antigens, 65(4), 370-378.

[4] Laux, G., Mansmann, U., Deufel, A., Opelz, G., & Mytilineos, J. (2003). A new epitope-based HLA-DPB matching approach for cadaver kidney retransplants. Transplantation, 75(9), 1527-1532.


Copyright © 2018, Geoffrey H. Smith, MD