Skip to main content

API design

Extensive JSON APIs allow you to interact with the data in your GGCE instance. The API endpoints ensure that the the business logic is properly applied and followed.

Access tokens​

All endpoints require a valid access token, and we will get to that in the next section.

Authorization

The HTTP header Authorization: Bearer <access token> 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 the user does not have permissions to access the operation or the data.

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 used to update the record. When a DTO references another object (e.g. the accession of an inventory), 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. accession's inventory records). 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.
  • Y and N values are now booleans true and false.

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>
ownedBy
string
ownedDate
string <date-time>
createdBy
string
createdDate
string <date-time>
modifiedBy
string
modifiedDate
required
string <date-time> (Last modified date)

Maintained by the server, original value must be included in all update and delete operations.

required
object (SiteInfo)
accessionNumber
string [ 0 .. 128 ] characters
preferredName
string
mlsStatus
string [ 0 .. 30 ] characters
accessionNumberPart1
required
string [ 0 .. 50 ] characters (^$)|(^\S+(?:\s\S+)*$)
accessionNumberPart2
integer <int64>
accessionNumberPart3
string [ 0 .. 50 ] characters
object (SiteInfo)
object (SiteInfo)
doi
string [ 0 .. 20 ] characters
improvementStatusCode
string
initialReceivedDate
string <date-time>
initialReceivedDateCode
string
initialReceivedFormCode
string
isBackedUp
boolean
isCore
boolean
isWebVisible
boolean
lifeFormCode
string
note
string
reproductiveUniformityCode
string
statusCode
string
curationTypeCode
string
required
object (TaxonomySpeciesInfo)
object (ExplorationInfo)
collectionCode
string

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 GGCE.

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 GGCE.

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 GGCE.

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 GGCE.
  • 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.