Homepage

Genesys API reference manual

August 2023: Documentation commit d83c996
version 2024.1

1. Security
- 1.1. Client credentials
- 1.2. Successful authorization
2. Client errors
- 2.1. 401 Unauthorized
3. Managing passport data
4. Acknowledgements

All API access is over HTTPS, and accessed from the https://api.genesys-pgr.org domain or through https://api.sandbox.genesys-pgr.org for testing purposes. All data is sent and received as JSON. In this manual, all URLs are pointing to the Genesys sandbox environment at https://api.sandbox.genesys-pgr.org.

1. Security

Access to selected resources in Genesys is protected and user permissions are checked before any API action is executed. Each organization contributing data to Genesys will have one or more registered user accounts on Genesys.

To modify any data in Genesys, you will need appropriate permissions. Permission to access and manage data for the organization is granted by helpdesk@genesys-pgr.org upon request. Please contact helpdesk@genesys-pgr.org with the list of FAO WIEWS codes of institutes you wish to manage.

To access resources with the APIs described in this manual, you will first need to create a user account.

Figure 1. Creating a user account

Using the APIs requires a valid access_token. As of 2023, Genesys uses Open ID Connect or OIDC.

To obtain OAuth access and refresh tokens, you will need a valid Client ID and Client Secret. These are generated by helpdesk@genesys-pgr.org for each individual client application. The ID and Secret listed below are valid for the Sandbox environment.

Table 1. Client ID and Secret for out-of-band authentication
Client ID	`dLCiR.MzwkNha18ImEcw0ADli0@sandbox.genesys-pgr.org`
Client Secret	`wGmRAhVplWLEVWlqiMT712PMnaqOa8FN`

We recommend that you use one of the certified or maybe uncertified OIDC libraries in your software.

In this example we will use Postman to connect to Genesys APIs.

Figure 2. Configuring Postman

Table 2. Postman configuration
Grant Type	Authorization code
Callback URL	`https://oauth.pstmn.io/v1/callback` (this is Postman default)
Auth(orization) URL	`https://api.sandbox.genesys-pgr.org/oauth/authorize`
Access token URL	`https://api.sandbox.genesys-pgr.org/oauth/token`
Client ID	`dLCiR.MzwkNha18ImEcw0ADli0@sandbox.genesys-pgr.org`
Client Secret	`wGmRAhVplWLEVWlqiMT712PMnaqOa8FN`
Client Authentication	Send as Basic Auth header

Then hit the Get New Access Token button and login to Genesys with your user credentials to get the token!

Test that you can interact with the Genesys API by making a GET request to https://api.sandbox.genesys-pgr.org/api/v1/me/profile using Postman.

1.1. Client credentials

System-to-system integration should not require user interaction. For that specific purpose, Genesys allows for an OAuth 2.1 client credentials grant.

Kindly contact helpdesk@genesys-pgr.org for information on how to enable system-to-system integration and to grant your client the appropriate permissions on Genesys.

To obtain athe access token, a simple POST request to Genesys is required:

$ curl -X POST 'https://api.sandbox.genesys-pgr.org/oauth/token?grant_type=client_credentials&client_id=CLIENTID&client_secret=SECRET'

This type of grant takes authenticates the remote system instead of an individual user, immediately issuing an access token.

1.2. Successful authorization

The server will respond with access token details in JSON format:

{
        "access_token": "28d96a4e-9a31-479b-abc8-17ee1e8c9906",
        "token_type": "bearer",
        "refresh_token": "2583fd78-bd88-4c2b-afc0-fb231b37d95f",
        "expires_in": 43199,
        "scope": "read write"
}

You can use the access token to sign future HTTP requests to the API by adding a HTTP request header:

Authorization: Bearer OAUTH-ACCESS-TOKEN

as a curl parameter:

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.sandbox.genesys-pgr.org/api/...

or by including it in the request URL as a query string parameter:

$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/me?_access_token=OAUTH-ACCESS-TOKEN'

2. Client errors

The API returns descriptive information in the response body about why the request failed to execute.

2.1. 401 Unauthorized

401 Unauthorized indicates that the request did not include valid authentication data. Check your OAuth access token.

401 Unauthorized error message

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
...
WWW-Authenticate: Bearer realm="genesys2", error="unauthorized", error_description="An Authentication object was not found in the SecurityContext"

{"error":"unauthorized","error_description":"An Authentication object was not found in the SecurityContext"}

3. Managing passport data

Passport data is based on the FAO/Bioversity Multi-crop Passport Descriptors (MCPD V.2.1) format.

Accession records are upserted, meaning that:

when the matching accession record exists, it will be updated.
when it does not exist, a new record will be created.

Accession data in the database will be updated with whatever data is provided in the request JSON. When a piece of information is not provided in JSON, it will not be modified. If it is set to null it will be removed from the Genesys database.

3.1. Accession identity

Prior to full adoption of DOIs for germplasm, accessions could be identified by the holding institute code (instituteCode) and the accession number (accessionNumber). However, genebanks maintaining two or more crop collections sometimes use identical accession numbers in separate crop collections.

For this reason, Genesys uses the instituteCode, accessionNumber and GENUS triplet to uniquely identify an accession. For accessions with a digital object identifier (DOI) assigned in the ITPGRFA Secretariat Global Information System (GLIS), it will use the DOI to uniquely identify the record.

Identifiers in an accession JSON object


  1
2
3
4
5
6
7
8
9

  {
        "doi": "10.1054/12A1~", (1)
        "instituteCode": "NGA039", (2)
        "accessionNumber": "TMp-123", (3)
        "taxonomy": {
                "genus": "Musa", (4)
        },
        ...
}

1	DOI of the accession as registered in GLIS
2	Holding institute code (instituteCode)
3	Accession number (accessionNumber)
4	Genus (GENUS)

3.2. JSON data model

This section was written in 2015 and is outdated.

The JSON data model of accession passport data closely follows MCPD definitions, but uses human readable property names. Collecting data is grouped under coll key, taxonomic data under taxonomy and geographic data under geo key.

By default, institutes in Genesys are configured to "Use unique accession numbers within the institute". The accession JSON object must provide two identifying elements: instituteCode and accessionNumber.

In cases where accession numbers are not unique within the institute, taxonomy.genus is used to identify the unique accession within the institute. In such a case the Accession JSON object must always provide three identifying elements: instituteCode, accessionNumber and taxonomy.genus. All other fields are optional.

Example fields in an accession JSON object


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

  {
        "doi": "10.1231/14S41Q",
        "instituteCode": "XYZ111",
        "accessionNumber": "M12345",
        "cropName": "banana",
        "taxonomy": {
                "genus": "Musa",
                "species": "acuminata",
                "spAuthor": "Colla",
                "subtaxa": "var. sumatrana",
                "subtAuthor": "(Becc.) Nasution"
        },
        "origCty": "NGA",
        "acquisitionDate": "20010301",
        "mlsStatus": true,
        "inTrust": false,
        "available": true,
        "historic": false,
        "storage": [ 10, 20 ],
        "sampStat": 200,
        "duplSite": [ "BEL084" ],
        "breederCode": [ "NGA039" ],
        "ancest": "PED/IG*REE",
        "remarks": [ "remark1", "remark2" ],
        "acceUrl": "https://my-genebank.org/accession/1",
        "geo": {
                ... (1)
        },
        "coll": {
                ... (2)
        }
}

1	JSON object with geographic data
2	JSON object with collecting data

3.3. Geographic data JSON model

The geo field in accession JSON captures geographic data.

Geographic data in a JSON object


  1
2
3
4
5
6
7
8

  {
        "latitude": 13.12312,
        "longitude": 42.2321,
        "elevation": 123.2,
        "uncertainty": 2000.0,
        "datum": "WGS84",
        "method": "GPS"
}

Table 3. Relevant MCPD descriptors
Field name	Description
DECLATITUDE	Latitude expressed in decimal degrees. Positive values are north of the Equator; negative values are south of the Equator (e.g. `-44.6975`).
DECLONGITUDE	Longitude expressed in decimal degrees. Positive values are east of the Greenwich Meridian; negative values are west of the Greenwich Meridian (e.g. `+120.9123`).
ELEVATION	Elevation of collecting site expressed in meters above sea level. Negative values are not allowed.
COORDUNCERT	Uncertainty associated with the coordinates in meters. Leave the value empty if the uncertainty is unknown.
COORDDATUM	The geodetic datum or spatial reference system upon which the coordinates given in decimal latitude and longitude are based (e.g. `WGS84`, `ETRS89`, `NAD83`). The GPS uses the WGS84 datum.
GEOREFMETH	The georeferencing method used (`GPS`, determined from `map`, `gazetteer`, or `estimated using software`). Leave the value empty if georeferencing method is not known.

3.4. Collecting data JSON model

The coll field in accession JSON captures collecting data.

Collecting data in a JSON object


  1
2
3
4
5
6
7
8
9
10

  {
        "collDate": "1990----",
        "collSite": "7km south of Curitiba in the state of Parana",
        "collNumb": "C90-23",
        "collSrc": 12,
        "collCode": [ "PER001" ],
        "collName": null,
        "collInstAddress": null,
        "collMissId": "C90"
}

Table 4. Relevant MCPD descriptors
Field name	Description
COLLDATE	Collecting date of the sample, in the format `YYYYMMDD`. Missing data (`MM` or `DD`) may be indicated with two hyphens or two zeros.
COLLSITE	Location information below the country level that describes where the accession was collected, preferably in English. This might include the distance in kilometers and direction from the nearest town, village or map grid reference point (e.g. `7km south of Curitiba in the state of Parana`).
COLLNUMB	Original identifier assigned by the collector(s) of the sample, normally composed of the name or initials of the collector(s) followed by a number (e.g. `FM9909`). This identifier is essential for identifying duplicates held in different collections.
COLLSRC	Collecting/acquisition source.
COLLCODE	FAO WIEWS code of the institute that collected the sample.
COLLNAME	Name of the institute that collected the sample. This descriptor should only be used if COLLCODE cannot be filled because the FAO WIEWS code for this institute is not available.
COLLINSTADDRESS	Address of the institute that collected the sample. This descriptor should only be used if COLLCODE cannot be filled because the FAO WIEWS code for this institute is not available.
COLLMISSID	Identifier of the collecting mission as used by the collecting institute (e.g. `CIATFOR-052`, `CN426`).

3.5. Clearing existing values

To reset or clear an existing value in the accession passport data, it should be provided as null. Not providing a field means the field in the database should not be modified.

Clearing the country of provenance from an accession record by sending a null value


  1
2
3
4
5
6
7
8

  {
        "instituteCode": "NGA039",
        "accessionNumber": "TMp-123",
        "taxonomy": {
                "genus": "Musa"
        },
        "origCty": null
}

3.6. Insert or update accessions

REST endpoint URL /api/v1/acn/{instituteCode}/upsert allows for inserting new accessions or updating existing records in Genesys. It accepts a JSON array of Accession JSON objects. The array provides for sending batches of 50 or 100 accessions in one call, reducing the HTTP overhead and improving performance.

Only the instituteCode and accessionNumber are required (and in some cases the taxonomy.genus). The server will return an error when the instituteCode of JSONs does not match the instituteCode in the URL!

3.7. Deleting accessions

With the introduction of permanent identifiers for accession records in Genesys we have also introduced the accession archive. The archive holds passport data for accession records that have been deleted from the active database.

REST endpoint URL /api/v1/acn/{instituteCode}/delete accepts an array of instituteCode, accessionNumber, genus triplets and deletes the corresponding accession records from Genesys. The DELETE permission is required for this operation.

The delete operation will fail if C&E data exists for any accessions listed.

Deleting three accessions from the active database


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  POST /api/v1/acn/SYR002/delete

[{
        "instituteCode": "SYR002",
        "accessionNumber": "12345",
        "taxonomy": { "genus": "Vicia" }
}, {
        "instituteCode": "SYR002",
        "accessionNumber": "12345",
        "taxonomy": { "genus": "Vicia" }
}, {
        "instituteCode": "SYR002",
        "accessionNumber": "IG 1",
        "taxonomy": { "genus": "Vicia" }
}]

3.8. Migrating from API v0

The v1 API uses a more self-explanatory JSON schema, adopting the internal Genesys property names in JSON de-/serialization, reducing the number of lines of code requried to parse and handle JSON input and output.

While the change made to the Java code are easier to read and maintain (for us), it requires data providers (you) to adopt the new naming scheme and update your software.

The primary change is the move from /api/*v0*/... endpoints to /api/*v1*/.... API v1 accepts and returns slightly different JSON compared to API v0.

Upgrade to v1 as soon as possible. The v0 API endpoints will be made obsolete in February 2020.

Genesys requires that breederCode, duplSite, collCode or donorCode use FAO WIEWS codes. Updating data will fail if existing or new records use invalid format (must be XXX000 or XXX0000).

3.8.1. Core accession properties

Table 5. Updated core properties
v0	v1	Notes
`instCode`	`instituteCode`	Holder institute code. Renamed for clarity.
`acceNumb`	`accessionNumber`	Accession number. Renamed for clarity.
`acqDate`	`acquisitionDate`	Date of acquisition. Renamed for clarity.
`bredCode`	`breederCode`	FAO WIEWS code of the institute that bred the material. Renamed for clarity. Accepts multiple values: `[ "XXX000", "YYY000" ]`
`bredName`	`breederName`	Name of the institute that bred the material. Renamed for clarity. Accepts multiple values: `[ "IITA", "CIMMYT" ]`
`mlsStat`	`mlsStatus`	MLS Status.
`orgCty`	`origCty`	ISO3166 code of provenance of material.

3.8.2. Taxonomic data

All taxonomic data was in the root JSON in v0 and is now grouped under taxonomy property.

Table 6. Updated properties for taxonomic data
v0	v1	Notes
`genus`	`taxonomy.genus`
`species`	`taxonomy.species`
`spauthor`	`taxonomy.spAuthor`	Note the uppercase `A`.
`subtaxa`	`taxonomy.subtaxa`
`subtauthor`	`taxonomy.subtAuthor`	Note the uppercase `A`.

3.8.3. Geographic data

Properties for geographic data under geo key are renamed:

Table 7. Updated properties for `geo` data
v0	v1	Notes
`geo.coordUncert`	`geo.uncertainty`	Distance of uncertainty of coordinates in meters.
`geo.coordDatum`	`geo.datum`	`WGS84` is most commonly used.
`geo.georefMeth`	`geo.method`	Method of georeferencing, text. Use values `GPS`, `Map` or similar.

3.8.4. Collecting data

Properties for collecting data in coll property are upgraded to support multiple values:

Table 8. Updated properties for `coll` data
v0	v1	Notes
`coll.collCode`	Same	Accepts multiple FAO WIEWS codes: `[ "XXX000", "ZZZ0000" ]`
`coll.collName`	Same	Accepts multiple values: `[ "collName1", "collName2" ]`
`coll.collInstAddress`	Same	Accepts multiple values: `[ "collInstAddress1", "collInstAddress2" ]`

4. Acknowledgements

Special thanks go to Luca Matteis and Richard Bruskiewich from Bioversity International who have contributed to the original documentation of the APIs.

Genesys API reference manual

Table of contents

1. Security

1.1. Client credentials

1.2. Successful authorization

2. Client errors

2.1. 401 Unauthorized

3. Managing passport data

3.1. Accession identity

3.2. JSON data model

3.3. Geographic data JSON model

3.4. Collecting data JSON model

3.5. Clearing existing values

3.6. Insert or update accessions

3.7. Deleting accessions

3.8. Migrating from API v0

3.8.1. Core accession properties

3.8.2. Taxonomic data

3.8.3. Geographic data

3.8.4. Collecting data

4. Acknowledgements