Genesys API reference manual

December 2015: Documentation commit 3e6ee0a8f51f06a6113c1575a510d583553985bd
version 2.0

All API access is over HTTPS, and accessed from the https://www.genesys-pgr.org domain or through https://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://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 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 is to use your Google+ account or alternatively creating an account manually.

user account create
Figure 1. Creating a user account

Access to the APIs is managed by OAuth 2.0 protocol and implemented using spring-security OAuth modules. All API access is over HTTPS, and accessed from the https://www.genesys-pgr.org domain or through https://sandbox.genesys-pgr.org for testing purposes.

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 allows of out-of-band authentication when using curl in the examples in this manual.

Table 1. Client ID and Secret for OOB

Client ID

dLCiR.MzwkNha18ImEcw0ADli0@sandbox.genesys-pgr.org

Client Secret

wGmRAhVplWLEVWlqiMT712PMnaqOa8FN

1.1. Obtaining the access token

Most OAuth libraries, including 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 the CLIENTID and SECRET with valid data):

https://sandbox.genesys-pgr.org/oauth/authorize?client_id=CLIENTID&client_secret=SECRET&response_type=code&redirect_uri=oob&scope=read%2Cwrite

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. Copy the authorization code: THECODE (looks like: 7wXP1r) and from shell, execute the curl command:

$ curl 'https://sandbox.genesys-pgr.org/oauth/token?grant_type=authorization_code&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob&code=THECODE'

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 curl parameter:

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

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

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

1.2. Using the refresh 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. Refresh token is returned as part of JSON response when 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 access token expires:

$ curl 'https://sandbox.genesys-pgr.org/oauth/token?grant_type=refresh_token&client_id=CLIENTID&client_secret=SECRET&redirect_uri=oob&refresh_token=OAUTH-REFRESH-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.

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 FAO Multi-Crop Passport Descriptors [mcpd2] format.

Accession records are upserted, meaning that when the matching accession record

  1. exists, it will be updated

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

3.1. Accession identity

Prior to full adoption of Permanent Unique Identifiers for Germplasm, accessions could be identified by the holding institute code (INSTCODE) and the accession number (ACCENUMB). Genebanks maintaining two or more collections of crops would sometimes use the same accession number, unique within one collection.

Genesys uses the instCode, acceNumb and genus triplet to uniquely identify an accession in an institute:


        
1
2
3
4
5
{
        "instCode": "NGA039", (1)
        "acceNumb": "TMp-123", (2)
        "genus": "Musa" (3)
}
1 Holding institute code (INSTCODE)
2 Accession number (ACCENUMB)
3 Genus (GENUS)

3.2. JSON data model

The JSON data model of accession passport data closely follows MCPD definitions.

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

In cases where accession numbers are not unique within the institute, genus is used to identify the unique accession within the institute. Then the Accession JSON object must always provide three identifying elements: instCode, acceNumb and 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
{
        "instCode": "XYZ111",
        "acceNumb": "M12345",
        "cropName": "banana",
        "genus": "Musa",
        "species": "acuminata",
        "spauthor": "Colla",
        "subtaxa": "var. sumatrana",
        "subtauthor": "(Becc.) Nasution",
        "orgCty": "NGA",
        "acqDate": "20010301",
        "mlsStat": true,
        "inTrust": false,
        "available": true,
        "historic": false,
        "storage": [10, 20],
        "sampStat": 200,
        "duplSite": "BEL084",
        "bredCode": "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:


        
1
2
3
4
5
6
7
8
{
        "latitude": 13.12312,
        "longitude": 42.2321,
        "elevation": 123.2,
        "coordUncert": 2000.0,
        "coordDatum": "WGS84",
        "georefMeth": "GPS"
}
Table 2. 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:


        
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 3. Relevant MCPD descriptors
Field name Description

COLLDATE

Collecting date of the sample, where YYYY is the year, MM is the month and DD is the day. Missing data (MM or DD) should be indicated with hyphens or 00 [double szero].

COLLSITE

Location information below the country level that describes where the accession was collected, preferable 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 collecting the sample.

COLLNAME

Name of the institute collecting 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 collecting 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 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.


        
1
2
3
4
5
6
{
        "instCode": "NGA039",
        "acceNumb": "TMp-123",
        "genus": "Musa",
        "orgCty": null (1)
}
1 Country of origin of accession is cleared by sending a null value.

3.6. Insert or update accessions

REST endpoint URL /api/v0/acn/{instCode}/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 instCode and acceNumb are required (And in some cases genus). NOTE: If a property is set to null, the existing value will be removed from the database. NOTE: The server will return an error when instCode of JSONs does not match the instCode 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/v0/acn/{instCode}/delete accepts an array of instCode, acceNumb, genus triplets and deletes corresponding accession record from Genesys. The DELETE permission is required for this operation.

Delete operation will fail if C&E data exists for any accessions listed.
Delete 3 accessions from active database

        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /api/v0/acn/SYR002/delete

[{
        "instCode": "SYR002",
        "acceNumb": "12345",
        "genus": "Vicia"
}, {
        "instCode": "SYR002",
        "acceNumb": "12345",
        "genus": "Vicia"
}, {
        "instCode": "SYR002",
        "acceNumb": "IG 1",
        "genus": "Vicia"
}]

4. Managing Accession Images

Institutes can upload accession images to Genesys repository. Genesys will store and maintain images and metadata provided by institutes and display the images with accession passport data.

Unique ACCENUMB

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 /api/v0/img/{instCode}/ namespace.

4.1. Listing existing galleries

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 /api/v0/img/{instCode}/_galleries endpoint:

$ curl 'https://sandbox.genesys-pgr.org/api/v0/img/XXX001/_galleries?page=1' -i -H 'Content-Type: application/json;charset=UTF-8'

4.1.1. Path parameters

Table 4. /api/v0/img/{instCode}/_galleries
Parameter Description

instCode

Institute WIEWS code (e.g. NGA039)

4.1.2. Request parameters

Parameter Description

page

The page to return (1 is first page)

4.1.3. Server response

The object returned by Genesys contains pagination information and basic image gallery 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

content

Array

Array containing request headers

numberOfElements

Number

Number of records in the content array

totalElements

Number

Total number of requests in Genesys belonging to this institute

size

Number

Page size

number

Number

Current page number

totalPages

Number

Page count

sort

Array

Arrray sorting details

4.2. Accepted image formats

Genesys allows for images in JPG and PNG format.

4.3. Adding images to accessions

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://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).

4.3.1. Path parameters

Table 5. /api/v0/img/{instCode}/acn/{acceNumb}/
Parameter Description

instCode

Institute WIEWS code (e.g. NGA039)

acceNumb

Existing ACCENUMB in the institute

4.3.2. Request parameters

Parameter Description

originalFilename

Filename of the image (e.g. IMG00121.jpg)

4.3.3. Server response

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 you 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 already stored in Genesys repository. Genesys also determines the image width, height and orientation from the image.

Path Type Description

uuid

String

UUID of the image in the Genesys repository

identifier

String

Unique identifier assigned to the image by Genesys

originalFilename

String

The original filename that you have provided

extension

String

Image extension derived from original filename (e.g. .jpg)

contentType

String

The content type of the image (autodetected when possible)

format

String

Image format

path

String

Location (directory) of the image in the Genesys repository

filename

String

The new generated filename of the image

url

String

The relative URL to the image in Genesys repository [path+filename]

sha1Sum

String

SHA1 hash of the image bytes

md5Sum

String

MD5 hash of the image bytes

width

Number

Image width in pixels (autodetected)

height

Number

Image height in pixels (autodetected)

orientation

String

LANDSCAPE or PORTRAIT orientation of the image (autodetected)

4.4. Updating image metadata

After a successful upload of the image to 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

String

Title is a property that refers to the name or names by which a resource is formally known

subject

String

The Subject described or pictured in the resource, accession number

description

String

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.

creator

String

An entity primarily responsible for making the resource

created

String

A point or period of time when the resource was created by the Creator

rightsHolder

String

Person or an organization owning or managing rights over this resource

accessRights

String

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.

license

String

Legal document giving official permission to do something with the resource. E.g. http://www.gnu.org/licenses/gpl.html

extent

String

Size (e.g. bytes, pages, inches, etc.) or duration (e.g. hours, minutes, days, etc.) of a resource

bibliographicCitation

String

Formal bibliographic citation for the resource

An example curl request is:

$ curl 'https://sandbox.genesys-pgr.org/api/v0/img/XXX001/acn/ACC001/3d297ba5-b6c6-4c8e-9bc9-f101c69167e3/_metadata' -i -X PUT -H 'Content-Type: application/json;charset=UTF-8' -d '{"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."}'

4.4.1. Path parameters

Table 6. /api/v0/img/{instCode}/acn/{acceNumb}/{uuid}/_metadata
Parameter Description

instCode

Institute WIEWS code (e.g. NGA039)

acceNumb

Existing ACCENUMB in the institute

uuid

UUID of the image in the gallery of this accession

4.4.2. Response fields

Server response


         
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

originalFilename

String

The original filename that you have provided

width

Number

Image width in pixels (autodetected)

height

Number

Image height in pixels (autodetected)

orientation

String

LANDSCAPE or PORTRAIT orientation of the image (autodetected)

format

String

Image format

identifier

String

Permanent unique identifier of the resource. Commonly a Uniform Resource Locator (URL).

title

String

Title is a property that refers to the name or names by which a resource is formally known

subject

String

The Subject described or pictured in the resource, accession number

description

String

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.

creator

String

An entity primarily responsible for making the resource

created

String

A point or period of time when the resource was created by the Creator

rightsHolder

String

Person or an organization owning or managing rights over this resource

accessRights

String

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.

license

String

Legal document giving official permission to do something with the resource. E.g. http://www.gnu.org/licenses/gpl.html

extent

String

Size (e.g. bytes, pages, inches, etc.) or duration (e.g. hours, minutes, days, etc.) of a resource

bibliographicCitation

String

Formal bibliographic citation for the resource

5. Managing Requests

Institutes can allow users to request for 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.

Requests and sub-requests

A client may request for 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 /api/v0/requests namespace.

5.1. Listing requests

To list all requests for the INSTCODE, you must have the ADMINISTRATOR permission on the institute record. Issue a GET request to /api/v0/requests/{instCode} endpoint:

$ curl 'https://sandbox.genesys-pgr.org/api/v0/requests/XXX001?page=0' -i

5.1.1. Path parameters

Table 7. /api/v0/requests/{instCode}
Parameter Description

instCode

Institute WIEWS code (e.g. NGA039)

5.1.2. Request parameters

Parameter Description

page

Page to request from the server

5.1.3. Server response

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

content

Array

Array containing request headers

numberOfElements

Number

Number of records in the content array

totalElements

Number

Total number of requests in Genesys belonging to this institute

size

Number

Page size

number

Number

Current page number

totalPages

Number

Page count

sort

Array

Arrray sorting details

5.2. Request details

To retrieve request details from Genesys:

$ curl 'https://sandbox.genesys-pgr.org/api/v0/requests/XXX001/r/a628ca16-fded-30f4-9cd1-93950a442107' -i -H 'Content-Type: application/json;charset=UTF-8'

5.2.1. Path parameters

Table 8. /api/v0/requests//{instCode}/r/{uuid}
Parameter Description

instCode

Institute WIEWS code (e.g. NGA039)

uuid

UUID of the request

5.2.2. Server response


         
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

uuid

String

The request UUID

version

Number

Record version indicator

instCode

String

WIEWS code of the institute handling the request

instEmail

String

Email address to which Genesys sends notifications

state

Number

The request STATE indicator

lastReminderDate

Null

Date of last email notification sent to institute

6. Managing Crop data

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

Crop Taxonomic rules

The common crop name of an accession in Genesys is determined by its taxonomy.

For example, crop banana includes accessions with genus Musa.

  1. Each crop and crop group defines its own taxonomic rules

  2. The genus, species and sub-species data of an accession is matched against all taxonomic rules

    1. Accession is linked with all matching crops

    2. Accession may have more than one "crop"

Managing crop data in Genesys is done through methods available in /api/v0/crops namespace.

6.1. Listing all crops

A number of crops and crop groups are usually defined and used in Genesys. To list all crops, issue a GET request to /api/v0/crops/ endpoint:

$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops' -i -H 'Content-Type: application/json;charset=UTF-8'

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

6.2. Retrieving crop data

The crop details are retrievable with a HTTP GET method to /api/v0/crops/{shortName}.

Table 9. /api/v0/crops/{shortName}
Parameter Description

shortName

Crop short name or code (e.g. maize)

Sample curl request to fetch maize crop definition
$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops/maize' -i -H 'Content-Type: application/json;charset=UTF-8'

The JSON representation of a single crop record includes the following fields:

Table 10. Fields of Crop records
Path Type Description

id

Number

Autogenerated ID

version

Number

Record version

name

String

Crop name in English

shortName

String

Crop short name or code (e.g. maize)

description

String

Crop description in English

active

Boolean

Record is active

otherNames

Array

Alternative spellings of the crop name

rdfUri

String

URI of RDF term describing the crop

i18n

String

i18n map

6.2.1. Taxonomic rules

The /api/v0/crops/{shortName}/rules endpoint exposes access to crop’s taxonomic rules. We mentioned earlier that accessions with genus Musa belong to bananas, similarly Zea genus belongs to maize.

Maize taxonomic rules
$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops/maize/rules' -i -H 'Content-Type: application/json;charset=UTF-8'

         
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 Genus Zea is included in maize when accession’s genus is Zea.
3 Species field is null meaning that accession species is ignored by this rule.
4 Subtaxa field is null meaninig that accession subtaxa value is ignored by this rule.

6.2.2. Exclusion rule

A rule can explicitly exclude accessions matching a particular combination of genus + species + subtaxa. This is useful for cases where you wish to include all Solanum species except for selected species (e.g. Solanum melongena).

6.3. Registering a new crop

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"
}
Table 11. Minimum required data to register a crop
Path Type Description

shortName

String

Crop short name or code (e.g. maize)

name

String

Crop name in English

otherNames

Array

Alternative spellings of the crop name

description

String

Crop description in English

The response is a single crop record as stored on the server.

Example request to register a new crop
$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{"shortName":"rice","name":"Rice","description":"Crop description in EN","otherNames":["ris","riž"]}'

6.4. Localization of crop title and description

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.

For example:


        
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": "香蕉和大蕉"
        }
}

6.5. Updating taxonomic rules

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"
}]
Setting new taxonomic rules for the selected crop
$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops/maize/rules' -i -X PUT -H 'Content-Type: application/json;charset=UTF-8' -d '[{"id":-121,"included":true,"genus":"Zea","species":"mays","subtaxa":"var. foobaria"}]'
Table 12. Taxonomic rule fields
Path Type Description

[].included

Boolean

Specifies whether the rule is an including or an excluding rule

[].genus

String

Accession is included in the crop when its genus matches specified value.

[].species

String

Accession is included in the crop when its species matches specified value.

[].subtaxa

String

Accession is included in the crop when its subtaxa matches specified value.

6.6. Deleting a crop

A crop record can be deleted by issuing a HTTP DELETE request to the /api/v0/crops/{shortName}. This will remove the crop and crop rules from the system.

Deleting a crop
$ curl 'https://sandbox.genesys-pgr.org/api/v0/crops/rice' -i -X DELETE -H 'Content-Type: application/json;charset=UTF-8'

7. Acknowledgements

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