IPD-IMGT/HLA Database Submission API Documentation
The IPD-IMGT/HLA Database Submission API allows users to submit data to the HLA database programmatically. The API is designed to be simple and easy to use, and is accessible via HTTP POST requests.
Endpoints: /cgi-bin/submission
| Method | Endpoint | Description |
|---|---|---|
| GET | https://www.ebi.ac.uk/cgi-bin/ipd/py/submission/run.cgi/ | Get version and environment for the submission API |
| POST | https://www.ebi.ac.uk/cgi-bin/ipd/py/submission/run.cgi/validate/ | Perform validation on a submission without commiting |
Responses
validate
The validation API will either return a successful JSON object, or failed JSON with the following fields:
Successful Response
{
"code": 201,
"flatfile": "{IPD-IMGT/HLA Flatfile}",
"message": "flatfile successfully validated",
"warnings": []
}Failed Response
{
"code": 422,
"message": "{descriptive error including the route to the invalid value and the reason it's invalid}"
}Schema
The JSON schema is included below:
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "http://example.com/example.json",
"type": "object",
"required": [
"submission_metadata",
"sequence_info",
"cell_info",
"methodology_info"
],
"properties": {
"submission_metadata": {
"type": "object",
"description": "Contains metadata related to the submission, including INSDC entries, hold submission flag, and submitter information.",
"required": [
"insdc_entries",
"submitter"
],
"properties": {
"insdc_entries": {
"type": "array",
"description": "An array of INSDC entries, each containing an accession and a public flag.",
"items": {
"type": "object",
"required": [
"accession"
],
"properties": {
"accession": {
"type": "string",
"description": "The accession number of the INSDC entry."
}
},
"minLength": 1
}
},
"hold_submission": {
"type": "boolean",
"description": "If true, submission will be held until the following release."
},
"submitter": {
"type": "object",
"description": "Contains information about the submitter, including the submitter ID and a list of emails.",
"required": [
"submitter",
"emails"
],
"properties": {
"submitter": {
"type": "string",
"pattern": "[0-9]{5}[A-Z][0-9]{2}",
"description": "The ID of the submitter, following the pattern of 5 digits, an uppercase letter, and 2 digits."
},
"emails": {
"type": "array",
"description": "A list of email addresses registered with the submitter.",
"items": {
"type": "string",
"description": "A registered email address."
},
"minLength": 1
}
}
}
}
},
"sequence_info": {
"type": "object",
"description": "Contains information about the sequence, including local name, level, contiguity, sequence, locus, description, and sequence coordinates.",
"required": [
"local_name",
"level",
"contiguous",
"sequence",
"locus",
"comparative_allele",
"description",
"sequence_coordinates"
],
"properties": {
"local_name": {
"type": "string",
"description": "The local name of the sequence."
},
"level": {
"type": "string",
"description": "The level of the sequence, either CDS or GEN.",
"anyOf": [
"CDS",
"GEN"
]
},
"contiguous": {
"type": "boolean",
"description": "Indicates whether the sequence is contiguous."
},
"sequence": {
"type": "string",
"pattern": "[ACTG]{200,}",
"description": "The nucleotide sequence, consisting of at least 200 characters of A, C, T, or G."
},
"locus": {
"type": "string",
"description": "The locus of the sequence."
},
"comparative_allele": {
"type": "string",
"description": "Single allele included in the 'description' that the submission is compared against. Must be included in the 'description' field."
},
"description": {
"type": "string",
"description": "A description of the sequence. Must include a comparative allele and a comparison against said allele. 'comparative_allele' must be mentioned within this field."
},
"sequence_coordinates": {
"type": "object",
"description": "Contains coordinates related to the sequence, including CDS and feature coordinates.",
"required": [
"cds_coords"
],
"properties": {
"cds_coords": {
"type": "array",
"description": "A list of features which describe the CDS features of the sequence.",
"items": {
"type": "object",
"required": [
"length",
"start"
],
"properties": {
"length": {
"type": "integer",
"description": "The length of the CDS feature."
},
"start": {
"type": "integer",
"description": "The start position of the CDS feature."
}
},
"minLength": 1
}
},
"feature_coords": {
"type": "array",
"description": "A list of features which describe all sequence features in the submission (exon, intron, utr). This field is required for genomic submissions, but not for CDS.",
"items": {
"type": "object",
"required": [
"length",
"number",
"start",
"type"
],
"properties": {
"length": {
"type": "integer",
"description": "The length of the feature."
},
"number": {
"type": "string",
"description": "The number of the feature. For utr features this should be '5' or '3'."
},
"start": {
"type": "integer",
"description": "The start position of the feature."
},
"type": {
"type": "string",
"description": "The type of the feature, either exon, intron, or utr.",
"anyOf": [
"exon",
"intron",
"utr"
]
}
}
}
}
}
}
}
},
"cell_info": {
"type": "object",
"description": "Contains information about cells, including their ID, ancestry, available material, and other attributes.",
"required": [
"cells"
],
"properties": {
"cells": {
"type": "array",
"description": "A list of cell objects.",
"items": {
"type": "object",
"required": [
"cell_id",
"ancestry",
"sex",
"cell_bank",
"consanguineous",
"homozygous",
"lab_of_origin",
"lab_contact",
"material_available",
"hla_typing"
],
"properties": {
"cell_id": {
"type": "string",
"description": "The unique identifier for the cell."
},
"other_names": {
"type": "string",
"description": "Other names or aliases for the cell."
},
"ancestry": {
"type": "object",
"description": "Ancestry information of the cell.",
"required": [
"broad"
],
"properties": {
"broad": {
"type": "string",
"anyOf": [
"Undefined",
"Admixed",
"European",
"Asian - South East Asian",
"African descent - African American",
"Asian - East Asian",
"Asian - South Asian",
"Greater Middle Eastern",
"Hispanic or Latin American",
"African",
"Oceanian",
"African - Sub-Sahran African",
"Native American",
"African or African Descent",
"African descent - Afro-Caribbean",
"Aboriginal Australian",
"Asian",
"Asian - Central Asia",
"African descent"
],
"description": "Broad ancestry category."
},
"region": {
"type": "string",
"description": "Region of ancestry.",
"anyOf": [
"Western Europe",
"Western Asia",
"Northern Europe",
"South America",
"Eastern Europe",
"South-Eastern Asia",
"Northern America",
"Eastern Asia",
"North America",
"Asia",
"Europe",
"Southern Asia",
"Northern Africa",
"Southern Europe",
"Central America",
"Central Asia",
"Africa",
"Polynesia",
"Eastern Africa",
"Western Africa",
"Caribbean",
"Australia And New Zealand",
"Southern Africa",
"Melanesia",
"Middle Africa"
]
},
"country": {
"type": "string",
"description": "Country of ancestry."
},
"local_designation": {
"type": "string",
"description": "Local designation of ancestry."
}
}
},
"sex": {
"type": "string",
"description": "Sex of the cell donor.",
"anyOf": [
"Male",
"Female",
"Other"
]
},
"consanguineous": {
"type": "string",
"description": "Indicates if the cell donor is consanguineous.",
"anyOf": [
"Yes",
"No",
"Unknown"
]
},
"homozygous": {
"type": "string",
"description": "Indicates if the cell donor is homozygous.",
"anyOf": [
"Yes",
"No",
"Unknown"
]
},
"comments": {
"type": "string",
"description": "Additional comments about the cell."
},
"lab_of_origin": {
"type": "string",
"description": "The lab where the cell originated."
},
"lab_contact": {
"type": "string",
"description": "Contact information for the lab of origin."
},
"material_available": {
"type": "string",
"description": "Information about available material."
},
"cell_bank": {
"type": "string",
"description": "The cell bank where the cell is stored."
},
"ihw": {
"type": "boolean",
"description": "Indicates if the cell is part of the International Histocompatibility Workshop."
},
"hla_typing": {
"type": "array",
"description": "HLA typing information for the cell.",
"items": {
"type": "object",
"required": [
"locus",
"typing",
"described"
],
"properties": {
"locus": {
"type": "string",
"description": "The HLA locus."
},
"typing": {
"type": "string",
"description": "The HLA typing result."
},
"described": {
"type": "boolean",
"description": "Indicates the HLA typing for the sequence included in the submission."
}
}
}
},
"serology": {
"type": "array",
"description": "Serology information for the cell.",
"items": {
"type": "object",
"required": [
"locus",
"serology"
],
"properties": {
"locus": {
"type": "string",
"description": "The serology locus."
},
"serology": {
"type": "string",
"description": "The serology result."
}
}
}
}
}
},
"minLength": 1
}
}
},
"methodology_info": {
"type": "object",
"description": "Contains information about the methodologies used, including sequencing and confirmation methods.",
"required": [
"sequencing_methods",
"confirmation_methods"
],
"properties": {
"sequencing_methods": {
"type": "array",
"description": "A list of sequencing methods used.",
"items": {
"type": "object",
"required": [
"method",
"source",
"minimum_requirements",
"primers"
],
"properties": {
"method": {
"type": "string",
"description": "The sequencing method used.",
"anyOf": [
"NGS Short Read",
"NGS Long Read (PacBio)",
"NGS Long Read (ONT)",
"NGS Dual Methodology",
"NGS Other",
"Non-NGS",
"WGS"
]
},
"source": {
"type": "string",
"description": "The DNA source used for sequencing.",
"anyOf": [
"PCR (Allele specific)",
"PCR (Locus specific)",
"Hybrid Capture"
]
},
"minimum_requirements": {
"type": "boolean",
"description": "Indicates if the method meets minimum requirements."
},
"primers": {
"type": "array",
"description": "A list of primers used in the sequencing method.",
"items": {
"type": "string"
}
},
"comments": {
"type": "string",
"description": "Additional comments about the sequencing method."
}
}
},
"minLength": 2
},
"confirmation_methods": {
"type": "array",
"description": "A list of confirmation methods used.",
"items": {
"type": "string",
"anyOf": [
{
"const": "PCR-SSO",
"description": "PCR-SSO confirmation used."
},
{
"const": "PCR-SSP",
"description": "PCR-SSP confirmation used."
},
{
"const": "Reverse-SSOP",
"description": "Reverse-SSOP confirmation used."
},
{
"const": "SBT",
"description": "SBT confirmation used."
}
]
}
}
}
}
}
}