Skip to content

GitLab

Genesys Backend
Genesys Backend
Commit 87b3184b authored by Matija Obreza's avatar Matija Obreza
Browse files
Options

Merge branch '237-update-documentation' into 'master' 

Resolve "Update documentation"

Closes #237

See merge request genesys-pgr/genesys-server!135
parents 3fdbd87f b6722c0e
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 371 additions and 413 deletions
src/main/asciidoc/api/accession.adoc
View file @ 87b3184b
[[chApiAccession]]
== Managing Passport Data
== Managing passport data
Passport data is based on FAO Multi-Crop Passport Descriptors <<mcpd2>> format.
Passport data is based on the FAO/Bioversity Multi-crop Passport Descriptors
(http://www.bioversityinternational.org/e-library/publications/detail/faobioversity-multi-crop-passport-descriptors-v2-mcpd-v2/[MCPD V.2]) format.
Accession records are *upserted*, meaning that when the matching accession record
Accession records are *upserted*, meaning that:
. exists, it will be updated
. does not exist, a new record will be created
. 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.
=== Accession identity
Prior to full adoption of Permanent Unique Identifiers for Germplasm, accessions could be
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.
However, genebanks maintaining two or more collections of crops sometimes use identical
accession numbers in different collections.
Genesys uses the *instCode*, *acceNumb* and *genus* triplet to uniquely identify an
accession in an institute. For accessions with a <<doi, DOI>> assigned in <<glis, GLIS>> it will
use the DOI to uniquely identify the record:
For this reason, Genesys uses the *INSTCODE*, *ACCENUMB* and *GENUS* triplet to uniquely identify an
accession. For accessions with a digital object identifier ( https://en.wikipedia.org/wiki/Digital_object_identifier[DOI]) assigned in the ITPGRFA Secretariat Global Information System (
http://www.fao.org/plant-treaty/areas-of-work/global-information-system/en/[GLIS]), it will
use the DOI to uniquely identify the record.
.Identifiers in an accession JSON object
[source,json,linenums]
----
{
......@@ -42,18 +45,18 @@ use the DOI to uniquely identify the record:
=== JSON data model
The JSON data model of accession passport data closely follows <<mcpd2, MCPD>> definitions.
The JSON data model of accession passport data closely follows
http://www.bioversityinternational.org/e-library/publications/detail/faobioversity-multi-crop-passport-descriptors-v2-mcpd-v2/[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
the unique accession within the institute. In such a case the Accession JSON object must always provide three
identifying elements: `instCode`, `acceNumb` and `genus`.
All other fields are optional.
.Example fields in an accession JSON object
[source,json,linenums]
----
{
......@@ -92,8 +95,9 @@ All other fields are optional.
=== Geographic data JSON model
The `geo` field in accession JSON captures geographic data:
The `geo` field in accession JSON captures geographic data.
.Geographic data in a JSON object
[source,json,linenums]
----
{
......@@ -112,21 +116,26 @@ The `geo` field in accession JSON captures geographic data:
|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`).
|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.
|===
=== Collecting data JSON model
The `coll` field in accession JSON captures collecting data:
The `coll` field in accession JSON captures collecting data.
.Collecting data in a JSON object
[source,json,linenums]
----
{
......@@ -147,20 +156,27 @@ The `coll` field in accession JSON captures collecting data:
|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].
|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,
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`).
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 collecting the sample.
|COLLNAME|Name of the institute collecting the sample. This descriptor should only be used if
|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 collecting the sample. This descriptor should only
|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 used by the Collecting Institute (e.g. `CIATFOR-052`, `CN426`).
|COLLMISSID|Identifier of the collecting mission as used by the collecting institute (e.g. `CIATFOR-052`, `CN426`).
|===
......@@ -169,16 +185,16 @@ The `coll` field in accession JSON captures collecting data:
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 origin from an accession by sending a `null` value
[source,json,linenums]
----
{
"instCode": "NGA039",
"acceNumb": "TMp-123",
"genus": "Musa",
"orgCty": null <1>
"orgCty": null
}
----
<1> Country of origin of accession is cleared by sending a `null` value.
=== Insert or update accessions
......@@ -187,25 +203,24 @@ or updating existing records in Genesys. It accepts a JSON array of Accession JS
The array provides for sending batches of 50 or 100 accessions in one call, reducing
the HTTP overhead and improving performance.
NOTE: 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!
NOTE: Only the `instCode` and `acceNumb` are required (and in some cases the `genus`).
The server will return an error when the `instCode` of JSONs does not match the `instCode` in the URL!
=== 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
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.
and deletes the corresponding accession records from Genesys. The *DELETE* permission is required for this operation.
NOTE: Delete operation will fail if C&E data exists for any accessions listed.
NOTE: The delete operation will fail if C&E data exists for any accessions listed.
.Delete 3 accessions from active database
.Deleting three accessions from the active database
[source,http,linenums]
----
POST /api/v0/acn/SYR002/delete
......@@ -224,11 +239,3 @@ POST /api/v0/acn/SYR002/delete
"genus": "Vicia"
}]
----
[bibliography]
- [[[mcpd2]]] Alercia, A; Diulgheroff, S; Mackay, M.
http://www.bioversityinternational.org/e-library/publications/detail/faobioversity-multi-crop-passport-descriptors-v2-mcpd-v2/[FAO/Bioversity Multi-Crop Passport Descriptors V.2]. 2012.
- [[[glis]]] ITPGRFA Secretariat
http://www.fao.org/plant-treaty/areas-of-work/global-information-system/en/[Global Information System].
src/main/asciidoc/api/crop.adoc
View file @ 87b3184b
[[chApiCrop]]
== Managing Crop data
== 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
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).
[NOTE]
.Crop Taxonomic rules
=====================================================================
The common crop name of an accession in Genesys is determined by its taxonomy.
=====================================================================
For example, crop https://www.genesys-pgr.org/c/banana[banana] includes accessions with genus _Musa_.
=== Crop taxonomic rules
The common crop name of an accession in Genesys is determined by its taxonomy.
For example, the crop https://www.genesys-pgr.org/c/banana[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
.. Accession is linked with all matching crops
.. Accession may have more than one "crop"
. 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 */api/v0/crops*
namespace.
Managing crop data in Genesys is done through methods available in the `/api/v0/crops` namespace.
=== 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:
crops, issue a `GET` request to the `/api/v0/crops/` endpoint:
include::{snippets}/crop-list/curl-request.adoc[]
The result is a JSON array of all crops in Genesys:
The result is a JSON array of all crops in Genesys.
.Start of a JSON array listing all crops in Genesys
[source,json,linenums]
----
[{
......@@ -53,42 +46,42 @@ The result is a JSON array of all crops in Genesys:
}, {
"id": 1,
"shortName": "banana",
"name": "Banana", ... <1>
"name": "Banana", ... <1>
}, {
"shortName": "barley",
"name": "Barley", ...
},
},
...]
----
<1> Some JSON elements removed for readability
<1> Some JSON elements removed for readability.
=== Retrieving crop data
The crop details are retrievable with a HTTP GET method to `/api/v0/crops/{shortName}`.
The crop details are retrievable with a `GET` request to `/api/v0/crops/{shortName}`.
[cols="1,3", options="header"]
.URL path parameters
include::{snippets}/crop-get/path-parameters.adoc[]
.Sample `curl` request to fetch maize crop definition
include::{snippets}/crop-get/curl-request.adoc[]
The JSON representation of a single crop record includes the following fields:
The JSON representation of a single crop record includes the following fields.
[cols="1,1,2", options="header"]
.Fields of *Crop* records
.Fields of crop records
include::{snippets}/crop-get/response-fields.adoc[]
==== 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.
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:
.Maize taxonomic rules
include::{snippets}/crop-rules-list/curl-request.adoc[]
.Result of request for maize taxonomic rules
[source,json,linenums]
----
[{
......@@ -96,25 +89,26 @@ include::{snippets}/crop-rules-list/curl-request.adoc[]
"included": true, <1>
"genus": "Zea", <2>
"species": null, <3>
"subtaxa": null <4>
"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.
<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.
==== 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
This is useful, for example, in order to include all accessions of the _Solanum_ genus except for selected species
(e.g. _Solanum melongena_).
=== Registering a new crop
To create a new crop, a JSON with the following data must be submitted:
To create a new crop, a JSON with the following data must be submitted.
.Data to register a crop
[source,json,linenums]
----
{
......@@ -130,7 +124,6 @@ include::{snippets}/crop-create/request-fields.adoc[]
The response is a single crop record as stored on the server.
.Example request to register a new crop
include::{snippets}/crop-create/curl-request.adoc[]
......@@ -138,11 +131,10 @@ include::{snippets}/crop-create/curl-request.adoc[]
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:
and `description` (for the description field) and second level keys corresponding to ISO_639_2
encoded vernacular language tags.
.Localized names and descriptions for genus Musa
[source,json,linenums]
----
{
......@@ -161,14 +153,14 @@ For example:
}
----
=== 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`:
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`
.Rule array to include multiple species in a crop
[source,json,linenums]
----
[{
......@@ -191,9 +183,8 @@ include::{snippets}/crop-rules-update/request-fields.adoc[]
=== Deleting a crop
A crop record can be deleted by issuing a HTTP DELETE request to the `/api/v0/crops/{shortName}`.
A crop record can be deleted by issuing an HTTP `DELETE` request to `/api/v0/crops/{shortName}`.
This will remove the crop and crop rules from the system.
.Deleting a crop
include::{snippets}/crop-delete/curl-request.adoc[]
src/main/asciidoc/api/images.adoc
View file @ 87b3184b
[[chApiImg]]
== Managing Accession Images
== Managing accession images
Institutes can upload accession images to Genesys repository. Genesys will store
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.
[NOTE]
.Unique ACCENUMB
=====================================================================
Genesys supports image galleries only for institutes that use unique ACCENUMB
within their institute.
=====================================================================
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.
Managing accession images in Genesys is done through methods available in the
`/api/v0/img/{instCode}/` namespace.
=== 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:
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:
include::{snippets}/img-instgallery-list/curl-request.adoc[]
......@@ -36,9 +30,10 @@ include::{snippets}/img-instgallery-list/request-parameters.adoc[]
==== Server response
The object returned by Genesys contains pagination information and basic image
gallery data in the `content` element:
The object returned by Genesys contains pagination information and basic image
gallery data in the `content` element.
.JSON `content` element returned for an INSTCODE request
[source,json,linenums]
----
{
......@@ -83,14 +78,14 @@ Genesys allows for images in JPG and PNG format.
=== 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:
`PUT` request, with the image bytes in the request body:
[source,bash]
----
$ 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
$ 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.
The request `Content-Type` header must be set to the image content type (e.g.
`image/png` or `image/jpeg`).
==== Path parameters
......@@ -104,9 +99,10 @@ include::{snippets}/img-instgallery-put/request-parameters.adoc[]
==== 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
and return the detailed image data, including the image *UUID* which is
required for subsequent updates of the image metadata or the image bytes.
.Server response to added image data
[source,json,linenums]
----
{
......@@ -119,7 +115,7 @@ required for subsequent updates of the image metadata or the image bytes.
"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"
"url": "/accessions/XXX001/acn/ACC001/16648001-72b5-4295-ad29-569a414ee8f1.jpg",
"sha1Sum": "160599e1ccd66e132a9b92bc845a9591fe948586",
"md5Sum": "c1887df421746e30a41b898956ea1f3e",
"width": 640,
......@@ -144,18 +140,19 @@ required for subsequent updates of the image metadata or the image bytes.
}
----
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`
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.
include::{snippets}/img-instgallery-put/response-fields.adoc[]
=== Updating image metadata
=== Updating image metadata
After a successful upload of the image to Genesys repository, you are able to
After a successful upload of an image to the Genesys repository, you are able to
manage the image metadata.
.Example image metadata
[source,json,linenums]
----
{
......@@ -172,7 +169,6 @@ manage the image metadata.
include::{snippets}/img-instgallery-metadata-put/request-fields.adoc[]
An example `curl` request is:
include::{snippets}/img-instgallery-metadata-put/curl-request.adoc[]
......@@ -183,8 +179,7 @@ include::{snippets}/img-instgallery-metadata-put/path-parameters.adoc[]
==== Response fields
Server response
.Server response with updated image metadata
[source,json,linenums]
----
{
......@@ -223,4 +218,3 @@ Server response
----
include::{snippets}/img-instgallery-metadata-put/response-fields.adoc[]
src/main/asciidoc/api/requests.adoc
View file @ 87b3184b
[[chApiRequests]]
== Managing Requests
== Managing requests
Institutes can allow users to request for material through Genesys. Genesys will
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.
https://mls.planttreaty.org/itt/[Easy-SMTA database].
Genesys maintains a database of requests received, confirmed and dispatched to
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.
[NOTE]
.Requests and sub-requests
=====================================================================
A client may request for material from several different genebanks in
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.
=====================================================================
email addresses registered with individual genebanks.
Managing crop data in Genesys is done through methods available in */api/v0/requests*
namespace.
Managing crop data in Genesys is done through methods available in the `/api/v0/requests` namespace.
=== 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:
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:
include::{snippets}/requests-inst-list/curl-request.adoc[]
......@@ -41,8 +37,9 @@ include::{snippets}/requests-inst-list/request-parameters.adoc[]
==== Server response
The object returned by Genesys contains pagination information and basic request data
in the `content` element:
in the `content` element.
.Request data returned by the server
[source,json,linenums]
----
{
......@@ -69,7 +66,7 @@ in the `content` element:
"ascending": false
}],
"first": true,
"numberOfElements": 1 <5>
"numberOfElements": 1, <5>
}
----
<1> Array containing request information
......
src/main/asciidoc/api/security.adoc
View file @ 87b3184b
......@@ -9,28 +9,26 @@ 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.
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 is to https://sandbox.genesys-pgr.org/google/login[use your Google+ account]
or alternatively https://sandbox.genesys-pgr.org/registration[creating an account manually].
create a user account. The simplest way is to https://sandbox.genesys-pgr.org/google/login[use your Google+ account],
or alternatively to https://sandbox.genesys-pgr.org/registration[create an account manually].
.Creating a user account
image::user-account-create.png[role="text-center"]
Access to the APIs is managed by https://en.wikipedia.org/wiki/OAuth#OAuth_2.0[OAuth 2.0] protocol and implemented
Access to the APIs is managed by the https://en.wikipedia.org/wiki/OAuth#OAuth_2.0[OAuth 2.0] protocol and implemented
using http://docs.spring.io/spring-security/oauth/[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.
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 allows of out-of-band authentication
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.
[cols="1,2"]
.Client ID and Secret for OOB
.Client ID and Secret for out-of-band authentication
|===
|Client ID
|`dLCiR.MzwkNha18ImEcw0ADli0@sandbox.genesys-pgr.org`
......@@ -41,17 +39,17 @@ when using `curl` in the examples in this manual.
=== Obtaining the access token
Most OAuth libraries, including https://gitlab.croptrust.org/genesys-pgr/genesys-client-api[genesys-client-api]
Most OAuth libraries, including the https://gitlab.croptrust.org/genesys-pgr/genesys-client-api[genesys-client-api]
Java library, will automatically obtain the access token following the OAuth protocol. This
section describes how to manually obtain the tokens.
==== Authorization Grant
==== Authorization grant
Log-in to Genesys with your account or Google+
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
initiated by opening the authorization URL in a browser (please substitute `CLIENTID` and `SECRET`
with valid data):
----
......@@ -59,46 +57,47 @@ https://sandbox.genesys-pgr.org/oauth/authorize?client_id=CLIENTID&client_secret
----