Skip to main content

API design

Extensive APIs allow you to interact with the data in Genesys.

Authorization header​

Authorization

The HTTP header Authorization must be present in every API request.

Unauthenticated requests and requests with an invalid access token will result in 401 Unauthorized HTTP error code.

403 Forbidden signifies that you do not have permissions to access the operation or the data.

Bearer token​

You can obtain your access token with OAuth.

Authorization: Bearer <access token>

API token​

API Token authentication is a recent addition to Genesys.

Authorization: API-Token <api token>

Data format​

The API responds with data in JSON format, and for requests that require a body, expects the body to be valid JSON.

Validating JSON

You can validate JSON on https://jsonlint.com

Data types​

The API uses a data transfer object (DTO type) to represent a record in the system. The DTO is also used to update the record. When a DTO references another object (e.g. the taxon of an accession), it will use only the basic information (Info type). This is a shorter, compact representation of the object that includes the key information, the ID and versioning information only. A DTO does not include lists of related objects (e.g. files attached to an accession). Instead, a special endpoint is sometimes available to fetch an object with detailed information (Detail type).

  • A DTO never includes lists of related (child) objects.
  • A DTO always references objects by their Info representation.
  • An Info type never makes use of DTO types.

The following are examples of DTO, Info and Detail types used by Accession endpoints.

The DTO carries information about an object. It never includes lists of related (child) objects, and always references objects by their Info representation.

AccessionDTO looks like this:

id
integer <int64>
active
boolean
version
integer <int32>
createdBy
string
createdDate
string <date-time>
lastModifiedBy
string
lastModifiedDate
string <date-time>
Array of objects (DatasetInfo)
Array of objects (SubsetInfo)
Array of objects (DiversityTreeInfo)
uuid
string <uuid>
Array of objects (AccessionListInfo) unique
object (PDCIInfo)
storage
Array of integers <int32> unique [ items <int32 > ]
duplSite
Array of strings unique
object (AccessionCollectInfo)
Array of objects (AccessionAliasInfo)
Array of objects (AccessionRemarkInfo)
breederCode
Array of strings unique
breederName
Array of strings unique
imageCount
integer <int32>
subsetCount
integer <int64>
datasetCount
integer <int64>
tileIndex3min
integer <int32>
object (AccessionGeo)
doi
string
dataProviderId
string [ 0 .. 100 ] characters
instituteCode
required
string [ 0 .. 10 ] characters [A-Z]{3}\d{3,4}
genus
string [ 0 .. 100 ] characters
required
object (FaoInstituteInfo)
accessionNumber
required
string [ 0 .. 128 ] characters
seqNo
number <double>
cropName
string [ 0 .. 100 ] characters
object (CropInfo)

Basic information of Genesys-managed crops and crop groups.

Genesys maps the different variations of crop names (MCPD: CROPNAME) provided by genebanks into a curated set of crops.

required
object (Taxonomy2Info)
acquisitionSource
string [ 0 .. 3 ] characters
acquisitionDate
string [ 0 .. 12 ] characters
origCty
string [ 0 .. 3 ] characters
object (CountryInfo)
sampStat
integer <int32>
inSvalbard
boolean
inTrust
boolean
available
boolean
historic
required
boolean
aegis
boolean
mlsStatus
boolean
acceUrl
string [ 0 .. 300 ] characters
accNames
string
otherIds
string
donorCode
string [ 0 .. 7 ] characters [A-Z]{3}\d{3,4}
donorName
string [ 0 .. 300 ] characters
donorNumb
string [ 0 .. 200 ] characters
ancest
string
curationType
string
Enum: "FULL" "PARTIAL" "ARCHIVED" "HISTORICAL"
sgsv
boolean
accessionName
string
genotyped
boolean
collection
string [ 1 .. 50 ] characters

Endpoint paths​

The common path prefix for the current version of the API is /api/v2. API operations are then grouped by the type of the record, and the same path prefix is used for that type:

TypePath prefixDescription
Accession/api/v2/aBusiness operations and CRUD endpoints.
For example, /api/v2/a/{id}/assign-doi that will submit the accession with id to ITPGRFA's DOI Registration Service and obtain a DOI for it.
AccessionSource/api/v2/a/sourceCRUD endpoints.
AccessionPedigree/api/v2/a/pedigreeCRUD endpoints.
Inventory/api/v2/iBusiness operations and CRUD endpoints.
InventoryViability/api/v2/i/viabilityBusiness operations and CRUD endpoints.

CRUD operations​

API provides create, read, update, delete (CRUD) endpoints for all types of records supported by Genesys.

Create a new record​

POST the object in request body to the corresponding .../XXX endpoint to create a new record of type XXX.

Validation

The record must have all the required fields and must pass all data validation constraints defined by Genesys.

Response​

The API will return the created object, including any auto-generated properties such as id, createdBy, createdDate (and barcode for Inventories).

  • Validation error: the provided record is invalid. It may be missing required fields or the data does not satisfy the constraints imposed by Genesys.

Read a record by its id​

GET the object by its id with the .../XXX/{id} endpoint.

Response​

The API will return the object matching the id. A 404 error means that there is no record with this id in the system.

Update an existing record​

PUT the updated object in request body to the .../XXX endpoint to update an existing record.

Concurrent updates

The modifiedDate of your updated object must not be different from what is stored on the server. When the two don't match, the server will respond with a HTTP error, meaning that your version of the record is outdated and should be reloaded.

Response​

The API will return the updated object. A 404 error means that there is no record with this id in the system.

Other errors include:

  • Validation error: your record is invalid. It may be missing required fields or the data does not satisfy the constraints imposed by Genesys.
  • Concurrency error: your version of the record is outdated according to modifiedDate.

Delete a record by id​

Use HTTP DELETE method on .../XXX/{id} endpoint to remove a record by its id.

Response​

The API will return the deleted object, including its id.

List records​

API provides a GET .../XXX/list endpoint that allows you to browse the records of that type.

All /list endpoints accept pagination parameters described below. They must be provided in the URL query string.

ParameterDescription
lSpecifies the requested size of the page. l is not required and a sensible default will be used by the API. Note that if the requested page length exceeds API limits, the API will return less than the requested number of records per page.
pDefaults to 0, representing the first page. The second page is 1, and so on.
sList of properties to sort the records. For example, s=name,id will sort the records by name, then by id, and return the requested page after sorting. Sorting is ascending by default.
dAllows you to specify the sort direction for the properties listed in s. For example, s=name,id&d=DESC,ASC is equivalent to ORDER BY name DESC, id ASC in SQL.

Response​

The response from the server contains the records and pagination information:

{
  "content": [ ], // array of records
  "number": 0, // page index
  "size": 100, // page size
  "numberOfElements": 100, // number of records on this page, can be less than "size"
  "totalElements": 134, // total number of records in the database
  "totalPages": 2,
  "first": true,
  "last": false,
  "sort": [ ]
}
  • content is the array of records that you're interested in, and it should contain numberOfElements objects.
  • number is the index of the returned page. It should correspond with the p parameter you submitted.
  • size is the size of the page. API may return less than the requested l records per page.
  • numberOfElements is usually the same as the size of the content array.
  • totalElements provides the total number of records in the database.
  • totalPages is calculated from totalElements / size.
  • first means API returned the first page (i.e. number === 0).
  • last means that the page is the last page (i.e. number === totalPages - 1).
  • sort provides sorting information applied by the server.