
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.
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. The simplest way is to use your Google+ account, or alternatively to create an account manually.
Access to the APIs is managed by the OAuth 2.0 protocol and implemented using spring-security OAuth modules. To obtain OAuth access and refresh tokens, you will first need a valid Client ID and Client Secret. These are generated by helpdesk@genesys-pgr.org for each individual consumer application. The ID and Secret listed below are valid for the Sandbox environment and allow out-of-band authentication when using curl
in the examples in this manual.
Client ID |
|
Client Secret |
|
Most OAuth libraries, including the genesys-client-api Java library, will automatically obtain the access token following the OAuth protocol. This section describes how to manually obtain the tokens.
Log in to Genesys with your account or Google+.
Obtain a verifier code by granting access to the "Genesys API reference" client. This is initiated by opening the authorization URL in a browser (please substitute CLIENTID
and SECRET
with valid data):
https://api.sandbox.genesys-pgr.org/oauth/authorize?client_id=CLIENTID&client_secret=SECRET&response_type=code&redirect_uri=oob&scope=write
The server will prompt you to authorize the access to your protected resources on Genesys. After your confirmation, the server will present an authorization code (which will look like: 7wXP1r
). From a shell, execute the following curl
command, with your authorization code in place of THECODE
:
$ curl 'https://api.sandbox.genesys-pgr.org/oauth/token?grant_type=authorization_code&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob&code=THECODE'
The password grant is available to trusted, secure clients (e.g. desktop applications) where the user’s password will not be captured or stored — i.e. it will be used once. A password grant can be used as follows:
$ curl 'https://api.sandbox.genesys-pgr.org/oauth/token' --data 'scope=write+read&grant_type=password&username=USERNAME&password=PASSWORD&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
System-to-system integration should not require user interaction. For that specific purpose, Genesys allows for an OAuth 2.0 client credentials grant.
With Genesys release 2.3, the client authentication grant is also supported. 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.
The client will be able to modify any data on Genesys on your behalf. |
For more details, read the section "Client Credential Grant" in A Guide To OAuth 2.0 Grants.
To obtain a valid (but short-lived) 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&redirect_uri=oob'
This type of grant takes out the user authentication and authenticates the remote system with Genesys, immediately issuing an access token.
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://sandbox.genesys-pgr.org
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'
OAuth access tokens have a fairly short lifetime. When an access token expires, the refresh token can be used to obtain a new access token. The refresh token is returned as part of the JSON response when a verification code is used to obtain the access token:
{
"access_token": "28d96a4e-9a31-479b-abc8-17ee1e8c9906",
"token_type": "bearer",
"refresh_token": "2583fd78-bd88-4c2b-afc0-fb231b37d95f",
"expires_in": 43199,
"scope": "read write"
}
The refresh token must be securely persisted and can be used to request a new access token when the previous access token expires:
$ curl 'https://api.sandbox.genesys-pgr.org/oauth/token?grant_type=refresh_token&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob&refresh_token=OAUTH-REFRESH-TOKEN'
The API returns descriptive information in the response body about why the request failed to execute.
401 Unauthorized indicates that the request did not include valid authentication data. Check your OAuth access token.
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"}
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.
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.
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) |
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.
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 |
The geo
field in accession JSON captures geographic data.
1
2
3
4
5
6
7
8
{
"latitude": 13.12312,
"longitude": 42.2321,
"elevation": 123.2,
"uncertainty": 2000.0,
"datum": "WGS84",
"method": "GPS"
}
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. |
DECLONGITUDE |
Longitude expressed in decimal degrees. Positive values are east of the Greenwich Meridian; negative values are west of the Greenwich Meridian (e.g. |
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. |
GEOREFMETH |
The georeferencing method used ( |
The coll
field in accession JSON captures collecting data.
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"
}
Field name | Description |
---|---|
COLLDATE |
Collecting date of the sample, in the format |
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. |
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. |
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. |
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.
null
value
1
2
3
4
5
6
7
8
{
"instituteCode": "NGA039",
"accessionNumber": "TMp-123",
"taxonomy": {
"genus": "Musa"
},
"origCty": null
}
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! |
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. |
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" }
}]
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). |
v0 | v1 | Notes |
---|---|---|
|
|
Holder institute code. Renamed for clarity. |
|
|
Accession number. Renamed for clarity. |
|
|
Date of acquisition. Renamed for clarity. |
|
|
FAO WIEWS code of the institute that bred the material. Renamed for clarity. Accepts multiple values: |
|
|
Name of the institute that bred the material. Renamed for clarity. Accepts multiple values: |
|
|
MLS Status. |
|
|
ISO3166 code of provenance of material. |
All taxonomic data was in the root JSON in v0 and is now grouped under taxonomy
property.
v0 | v1 | Notes |
---|---|---|
|
|
|
|
|
|
|
|
Note the uppercase |
|
|
|
|
|
Note the uppercase |
Properties for geographic data under geo
key are renamed:
v0 | v1 | Notes |
---|---|---|
|
|
Distance of uncertainty of coordinates in meters. |
|
|
|
|
|
Method of georeferencing, text. Use values |
Properties for collecting data in coll
property are upgraded to support multiple values:
v0 | v1 | Notes |
---|---|---|
|
Same |
Accepts multiple FAO WIEWS codes: |
|
Same |
Accepts multiple values: |
|
Same |
Accepts multiple values: |
Institutes can upload accession images to the Genesys repository. Genesys will store and maintain images and metadata provided by institutes and display the images with accession passport data.
Genesys supports image galleries only for institutes that use unique ACCENUMB within their institute. |
Managing accession images in Genesys is done through methods available in the /api/v0/img/{instCode}/
namespace.
To list existing accession image galleries for the INSTCODE, you must have the WRITE
or CREATE
permission on the institute record. Issue a GET
request to the /api/v0/img/{instCode}/_galleries
endpoint:
$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/img/XXX001/_galleries?page=1' -i -X GET \
-H 'Content-Type: application/json'
Parameter | Description |
---|---|
|
Institute WIEWS code (e.g. NGA039) |
The object returned by Genesys contains pagination information and basic image gallery data in the content
element.
content
element returned for an INSTCODE request
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
{
"content": [{
"uuid": "4422e87e-52fe-38ef-b04a-079e663dd3da",
"version": 0,
"instCode": "XXX001",
"instEmail": "institute@localhost",
"state": 0,
"createdDate": null,
"lastModifiedDate": null,
"lastReminderDate": null
}], (1)
"last": true,
"totalElements": 1, (2)
"totalPages": 1, (3)
"size": 10, (4)
"number": 0,
"sort": [{
"direction": "DESC",
"property": "createdDate",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}],
"first": true,
"numberOfElements": 1 (5)
}
1 | Array containing request information |
2 | Number of elements in the Genesys database |
3 | Number of pages |
4 | Page size |
5 | Number of elements in the content array |
Path | Type | Description |
---|---|---|
|
|
Array containing request headers |
|
|
Request UUID |
|
|
WIEWS institute code |
|
|
Institute email address to which request was relayed |
|
|
Request state |
|
|
Date when request was created |
|
|
Date when request was last relayed to specified email address |
|
|
The UUID of source request |
|
|
Number of records in the content array |
|
|
Total number of requests in Genesys belonging to this institute |
|
|
Page size |
|
|
Current page number |
|
|
Page count |
|
|
Array sorting details |
To add images to an accession you must first upload the image to Genesys with a PUT
request, with the image bytes in the request body:
$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/img/XXX001/acn/ACC001/?originalFilename=IMG0012.jpg' -i -X PUT -H 'Content-Type: image/jpeg' -d @path/to/IMG0012.jpg
The request Content-Type
header must be set to the image content type (e.g. image/png
or image/jpeg
).
Parameter | Description |
---|---|
|
Institute WIEWS code (e.g. NGA039) |
|
Existing ACCENUMB in the institute |
Parameter | Description |
---|---|
|
Filename of the image (e.g. IMG00121.jpg) |
As Genesys accepts the image data, it will create a blank image metadata record and return the detailed image data, including the image UUID which is required for subsequent updates of the image metadata or the image bytes.
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
33
{
"id": 1,
"contentType": "image/jpeg",
"format": "image/jpeg",
"uuid": "16648001-72b5-4295-ad29-169a414ee8f1",
"identifier": "urn:uuid:16648001-72b5-4295-ad29-569a414ee8f1",
"originalFilename": "maize.jpg",
"extension": ".jpg",
"path": "/accessions/XXX001/acn/ACC001/",
"filename": "16648001-72b5-4295-ad29-569a414ee8f1.jpg",
"url": "/accessions/XXX001/acn/ACC001/16648001-72b5-4295-ad29-569a414ee8f1.jpg",
"sha1Sum": "160599e1ccd66e132a9b92bc845a9591fe948586",
"md5Sum": "c1887df421746e30a41b898956ea1f3e",
"width": 640,
"height": 427,
"orientation": "LANDSCAPE",
"title": null,
"subject": null,
"description": null,
"creator": null,
"created": null,
"rightsHolder": null,
"accessRights": null,
"license": null,
"extent": null,
"bibliographicCitation": null,
"createdDate": null,
"lastModifiedDate": null,
"originalUrl": null,
"dateRetrieved": null,
"dateSubmitted": null,
"modified": null,
}
You will observe that most metadata is null
, but the image bytes are now stored in the Genesys repository. Genesys also determines the image width
, height
and orientation
from the image.
Path | Type | Description |
---|---|---|
|
|
UUID of the image in the Genesys repository |
|
|
Unique identifier assigned to the image by Genesys |
|
|
The original filename that you have provided |
|
|
Image extension derived from original filename (e.g. .jpg) |
|
|
The content type of the image (autodetected when possible) |
|
|
Image format |
|
|
Image size in bytes |
|
|
Location (directory) of the image in the Genesys repository |
|
|
The generated filename |
|
|
The folder where bytes are stored |
|
|
Path to the bytes in storage |
|
|
The generated filename for image metadata |
|
|
SHA1 hash of the image bytes |
|
|
MD5 hash of the image bytes |
|
|
Image width in pixels (autodetected) |
|
|
Image height in pixels (autodetected) |
|
|
LANDSCAPE or PORTRAIT orientation of the image (autodetected) |
|
|
Thumbnails folder |
After a successful upload of an image to the Genesys repository, you are able to manage the image metadata.
1
2
3
4
5
6
7
8
9
10
{
"title": "Leaf of ACC001",
"subject": "ACC001",
"description": "Image of leaf of ACC001 taken ...",
"creator": "John Doe",
"rightsHolder": "International Institute of Accessions (IIA)",
"accessRights": "Access rights",
"license": "https://creativecommons.org/publicdomain/zero/1.0/",
"bibliographicCitation": "Genesys Museum in Bonn. Digital image. Accession Imagery. Genesys. Web. 9 August 2016."
}
Path | Type | Description |
---|---|---|
|
|
Title is a property that refers to the name or names by which a resource is formally known |
|
|
The Subject described or pictured in the resource, accession number |
|
|
Description of the content of a resource. The description is a potentially rich source of indexable terms and assist the users in their selection of an appropriate resource. |
|
|
An entity primarily responsible for making the resource |
|
|
A point or period of time when the resource was created by the Creator |
|
|
Person or an organization owning or managing rights over this resource |
|
|
Access rights provides information about restrictions to view, search or use a resource based on attributes of the resource itself or the category of user. |
|
|
Legal document giving official permission to do something with the resource. E.g. http://www.gnu.org/licenses/gpl.html |
|
|
Size (e.g. bytes, pages, inches, etc.) or duration (e.g. hours, minutes, days, etc.) of a resource |
|
|
Formal bibliographic citation for the resource |
An example curl
request is:
$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/img/XXX001/acn/ACC001/8ecdea45-9101-40f8-9877-a17c44a90438/_metadata' -i -X PUT \
-H 'Content-Type: application/json' \
-d '{"active":true,"title":"Leaf of ACC001","subject":"ACC001","description":"Image of leaf of ACC001 taken ...","creator":"John Doe","created":"August 2016","rightsHolder":"International Institute of Accessions (IIA)","accessRights":"Access rights","license":"https://creativecommons.org/publicdomain/zero/1.0/","extent":"4000x2000 pixels, 10MB","bibliographicCitation":"Genesys Museum in Bonn. Digital image. Accession Imagery. Genesys. Web. 9 August 2016.","size":0,"width":0,"height":0,"_class":"RepositoryImage"}'
Parameter | Description |
---|---|
|
Institute WIEWS code (e.g. NGA039) |
|
Existing ACCENUMB in the institute |
|
UUID of the image in the gallery of this accession |
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
33
{
"id": 1,
"uuid": "1e23549e-a882-40b4-abc8-0a4708ba7ff3",
"path": "/accessions/XXX001/acn/ACC001/",
"originalFilename": "maize.jpg",
"extension": ".jpg",
"title": "Leaf of ACC001",
"subject": "ACC001",
"description": "Image of leaf of ACC001 taken ...",
"creator": "John Doe",
"created": null,
"rightsHolder": "International Institute of Accessions (IIA)",
"accessRights": "Access rights",
"license": "https://creativecommons.org/publicdomain/zero/1.0/",
"contentType": "image/jpeg",
"extent": null,
"bibliographicCitation": "Genesys Museum in Bonn. Digital image. Accession Imagery. Genesys. Web. 9 August 2016.",
"createdDate": null,
"lastModifiedDate": null,
"originalUrl": null,
"dateRetrieved": null,
"sha1Sum": "160599e1ccd66e132a9b92bc845a9591fe948586",
"md5Sum": "c1887df421746e30a41b898956ea1f3e",
"width": 640,
"height": 427,
"orientation": "LANDSCAPE",
"identifier": "urn:uuid:1e23549e-a882-40b4-abc8-0a4708ba7ff3",
"dateSubmitted": null,
"modified": null,
"format": "image/jpeg",
"url": "/accessions/XXX001/acn/ACC001/1e23549e-a882-40b4-abc8-0a4708ba7ff3.jpg",
"filename": "1e23549e-a882-40b4-abc8-0a4708ba7ff3.jpg"
}
Path | Type | Description |
---|---|---|
|
|
The original filename that you have provided |
|
|
Location (directory) of the image in the Genesys repository |
|
|
The generated filename |
|
|
The folder where bytes are stored |
|
|
Image width in pixels (autodetected) |
|
|
Image height in pixels (autodetected) |
|
|
LANDSCAPE or PORTRAIT orientation of the image (autodetected) |
|
|
Image format |
|
|
Permanent unique identifier of the resource. Commonly a Uniform Resource Locator (URL). |
|
|
Title is a property that refers to the name or names by which a resource is formally known |
|
|
The Subject described or pictured in the resource, accession number |
|
|
Description of the content of a resource. The description is a potentially rich source of indexable terms and assist the users in their selection of an appropriate resource. |
|
|
An entity primarily responsible for making the resource |
|
|
A point or period of time when the resource was created by the Creator |
|
|
Person or an organization owning or managing rights over this resource |
|
|
Access rights provides information about restrictions to view, search or use a resource based on attributes of the resource itself or the category of user. |
|
|
Legal document giving official permission to do something with the resource. E.g. http://www.gnu.org/licenses/gpl.html |
|
|
Size (e.g. bytes, pages, inches, etc.) or duration (e.g. hours, minutes, days, etc.) of a resource |
|
|
Formal bibliographic citation for the resource |
|
|
Image size in bytes |
|
|
Image width in pixels |
|
|
Image height in pixels |
Institutes can allow users to request material through Genesys. Genesys will validate the user’s email address (by waiting for them to click the confirmation link sent to their address) and also check if the user is registered with ITPGRFA’s Easy-SMTA database.
Genesys maintains a database of requests received, confirmed and dispatched to genebanks holding the requested materials. This API allows genebanks to retrieve the request data from Genesys for automated integration into their existing information systems.
A client may request material from several different genebanks in one session. Genesys splits the request and dispatches sub-requests to email addresses registered with individual genebanks. |
Managing crop data in Genesys is done through methods available in the /api/v0/requests
namespace.
To list all requests for a given INSTCODE, you must have the ADMINISTRATOR
permission on the institute record. Issue a GET
request to the /api/v0/requests/{instCode}
endpoint:
$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/requests/XXX001?page=0' -i -X GET
Parameter | Description |
---|---|
|
Institute WIEWS code (e.g. NGA039) |
The object returned by Genesys contains pagination information and basic request data in the content
element.
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
{
"content": [{
"uuid": "4422e87e-52fe-38ef-b04a-079e663dd3da",
"version": 0,
"instCode": "XXX001",
"instEmail": "institute@localhost",
"state": 0,
"createdDate": null,
"lastModifiedDate": null,
"lastReminderDate": null
}], (1)
"last": true,
"totalElements": 1, (2)
"totalPages": 1, (3)
"size": 10, (4)
"number": 0,
"sort": [{
"direction": "DESC",
"property": "createdDate",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}],
"first": true,
"numberOfElements": 1, (5)
}
1 | Array containing request information |
2 | Number of elements in the Genesys database |
3 | Number of pages |
4 | Page size |
5 | Number of elements in the content array |
Path | Type | Description |
---|---|---|
|
|
Array containing request headers |
|
|
Request UUID |
|
|
WIEWS institute code |
|
|
Institute email address to which request was relayed |
|
|
Request state |
|
|
Date when request was created |
|
|
Date when request was last relayed to specified email address |
|
|
The UUID of source request |
|
|
Number of records in the content array |
|
|
Total number of requests in Genesys belonging to this institute |
|
|
Page size |
|
|
Current page number |
|
|
Page count |
|
|
Array sorting details |
To retrieve request details from Genesys:
$ curl 'https://api.sandbox.genesys-pgr.org/api/v0/requests/XXX001/r/14784c7a-e548-4f04-a258-94fd534db617' -i -X GET \
-H 'Content-Type: application/json'
Parameter | Description |
---|---|
|
Institute WIEWS code (e.g. NGA039) |
|
UUID of the request |
1
2
3
4
5
6
7
8
9
10
{
"uuid": "7ecb3c6e-63d8-3869-b2c7-28571c9e2864",
"version": 0,
"instCode": "XXX001",
"instEmail": "institute@localhost",
"state": 0,
"createdDate": null,
"lastModifiedDate": null,
"lastReminderDate": null
}
Path | Type | Description |
---|---|---|
|
|
The request UUID |
|
|
Record version indicator |
|
|
WIEWS code of the institute handling the request |
|
|
Email address to which Genesys sends notifications |
|
|
The UUID of source request |
|
|
The request STATE indicator |
|
|
Date of last email notification sent to institute |
Genesys maintains a database of crops and crop groups (e.g. forages). In addition to the general description, each crop defines a list of taxonomic rules that determine which taxonomies are included (or excluded) in the group.
Crops and crop groups are referred to and identified by the crop’s short name. The short name placeholder in documentation below is marked by {shortName}
. The short name should have no spaces and it should contain US-ASCII characters only (a-Z, 0-9).
The common crop name of an accession in Genesys is determined by its taxonomy. For example, the crop banana includes accessions of the genus Musa.
Each crop and crop group defines its own taxonomic rules.
The genus, species and sub-species data of an accession is matched against all taxonomic rules.
The accession is linked with all matching crops.
The accession may have more than one "crop".
Managing crop data in Genesys is done through methods available in the /api/v0/crops
namespace.
A number of crops and crop groups are usually defined and used in Genesys. To list all crops, issue a GET
request to the /api/v0/crops/
endpoint:
$ curl 'https://api.genesys-pgr.org/api/v2/crops' -i -X GET \
-H 'Content-Type: application/json'
The result is a JSON array of all crops in Genesys.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[{
"id": 27,
"version": 1,
"rdfUri": null,
"shortName": "apple",
"name": "Apple",
"description": null,
"i18n": "{\"name\":{\"fa\":\"سیب\"}}"
}, {
"id": 1,
"shortName": "banana",
"name": "Banana", ... (1)
}, {
"shortName": "barley",
"name": "Barley", ...
},
...]
1 | Some JSON elements removed for readability. |
The crop details are retrievable with a GET
request to /api/v0/crops/{shortName}
.
Parameter | Description |
---|---|
|
Crop short name or code (e.g. maize) |
curl
request to fetch maize crop definition
$ curl 'https://api.genesys-pgr.org/api/v2/crops/maize' -i -X GET \
-H 'Content-Type: application/json'
The JSON representation of a single crop record includes the following fields.
Path | Type | Description |
---|---|---|
|
|
Autogenerated ID |
|
|
Record version |
|
|
Crop name in English |
|
|
Crop short name or code (e.g. maize) |
|
|
Crop description in English |
|
|
URI of RDF term describing the crop |
|
|
i18n map |
|
|
Alternative spellings of the crop name |
The /api/v0/crops/{shortName}/rules
endpoint exposes access to a crop’s taxonomic rules. We mentioned earlier that accessions with the genus Musa belong to bananas; similarly, accessions of the Zea genus belong to maize:
Unresolved directive in api/crop.adoc - include::/builds/genesys-pgr/genesys-server/target/generated-snippets/crop-rules-list/curl-request.adoc[]
1
2
3
4
5
6
7
[{
"id": 24,
"included": true, (1)
"genus": "Zea", (2)
"species": null, (3)
"subtaxa": null, (4)
}]
1 | The combination of genus, species and subtaxa can be either included or explicitly excluded from the crop. |
2 | An accession is included in maize when accession’s genus value is Zea . |
3 | Species field is null meaning that accession species is ignored by this rule. |
4 | Subtaxa field is null meaning that accession subtaxa value is ignored by this rule. |
To create a new crop, a JSON with the following data must be submitted.
1
2
3
4
5
{
"shortName": "maize",
"name": "Maize",
"description": "Crop description in EN"
}
Path | Type | Description |
---|---|---|
|
|
Crop short name or code (e.g. maize) |
|
|
Crop name in English |
|
|
Crop description in English |
The response is a single crop record as stored on the server.
$ curl 'https://api.genesys-pgr.org/api/v1/crops/save' -i -X POST \
-H 'Content-Type: application/json' \
-d '{"shortName":"rice","name":"Rice","description":"Crop description in EN"}'
The i18n
field of the JSON crop object is a string encoded JSON object of a two level JSON formatted dictionary string with first level keys name
(for the name field) and description
(for the description field) and second level keys corresponding to ISO_639_2 encoded vernacular language tags.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"name": {
"en": "Musa",
"es": "Musa",
"ru": "Муса",
"zh": "穆萨"
},
"description": {
"en": "Bananas and plantains",
"es": "Los bananos y plátanos",
"ru": "Бананы и бананы",
"zh": "香蕉和大蕉"
}
}
Taxonomic rules can be replaced using one call by providing the new list of rules as the body of the HTTP PUT
call to /api/v0/crops/{shortName}/rules
. To specify that all Triticum and Aegilops species should be included in wheat, you would send the following array of rules to /api/v0/crops/wheat/rules
1
2
3
4
5
6
7
[{
"included": true,
"genus": "Triticum"
}, {
"included": true,
"genus": "Aegilops"
}]
Unresolved directive in api/crop.adoc - include::/builds/genesys-pgr/genesys-server/target/generated-snippets/crop-rules-update/curl-request.adoc[]
Unresolved directive in api/crop.adoc - include::/builds/genesys-pgr/genesys-server/target/generated-snippets/crop-rules-update/request-fields.adoc[]