Commit 7705555e authored by Matija Obreza's avatar Matija Obreza

spring-restdocs

parent 87542768
...@@ -115,6 +115,12 @@ ...@@ -115,6 +115,12 @@
<version>1.3</version> <version>1.3</version>
<scope>test</scope> <scope>test</scope>
</dependency> </dependency>
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<version>1.0.1.RELEASE</version>
<scope>test</scope>
</dependency>
<dependency> <dependency>
<groupId>commons-beanutils</groupId> <groupId>commons-beanutils</groupId>
...@@ -641,9 +647,11 @@ ...@@ -641,9 +647,11 @@
</goals> </goals>
<configuration> <configuration>
<backend>html5</backend> <backend>html5</backend>
<doctype>book</doctype>
<sourceHighlighter>coderay</sourceHighlighter> <sourceHighlighter>coderay</sourceHighlighter>
<attributes> <attributes>
<linkcss>true</linkcss> <copycss>true</copycss>
<!-- <linkcss /> -->
<toc>left</toc> <toc>left</toc>
<icons>font</icons> <icons>font</icons>
<sectanchors>true</sectanchors> <sectanchors>true</sectanchors>
...@@ -653,7 +661,7 @@ ...@@ -653,7 +661,7 @@
</attributes> </attributes>
</configuration> </configuration>
</execution> </execution>
<execution> <!-- <execution>
<id>output-docbook</id> <id>output-docbook</id>
<phase>generate-resources</phase> <phase>generate-resources</phase>
<goals> <goals>
...@@ -663,7 +671,7 @@ ...@@ -663,7 +671,7 @@
<backend>docbook</backend> <backend>docbook</backend>
<doctype>book</doctype> <doctype>book</doctype>
</configuration> </configuration>
</execution> </execution> -->
</executions> </executions>
<configuration> <configuration>
<sourceDirectory>src/main/asciidoc</sourceDirectory> <sourceDirectory>src/main/asciidoc</sourceDirectory>
...@@ -672,9 +680,10 @@ ...@@ -672,9 +680,10 @@
<numbered>true</numbered> <numbered>true</numbered>
<!-- <imagesDir>images</imagesDir> --> <!-- <imagesDir>images</imagesDir> -->
<attributes> <attributes>
<buildNumber>${buildNumber}</buildNumber> <buildNumber>${buildNumber}</buildNumber>
<projectArtifact>${project.artifactId}</projectArtifact> <projectArtifact>${project.artifactId}</projectArtifact>
<projectVersion>${project.version}</projectVersion> <projectVersion>${project.version}</projectVersion>
<snippets>${snippetsDirectory}</snippets>
</attributes> </attributes>
</configuration> </configuration>
</plugin> </plugin>
......
Genesys API reference manual
============================
December 2015: Documentation commit {buildNumber}
:revnumber: {projectVersion}
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:numbered:
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
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.
include::sections/security.adoc[]
include::sections/accession-api.adoc[]
...@@ -37,7 +37,7 @@ This file needs to be created in a location that is included on the webapplicati ...@@ -37,7 +37,7 @@ This file needs to be created in a location that is included on the webapplicati
[[genesys-configuration-options]] [[genesys-configuration-options]]
=== Configuration options === Configuration options
==== HTTP, CDN and cookie configuration ==== HTTP, CDN and cookies
[cols="1,1,3", options="header"] [cols="1,1,3", options="header"]
.HTTP-related configuration .HTTP-related configuration
...@@ -171,7 +171,7 @@ Genesys uses a number of external service APIs to provide users with advanced fu ...@@ -171,7 +171,7 @@ Genesys uses a number of external service APIs to provide users with advanced fu
|news.menu.abbreviate.length|22|The maximum length for abbreviated menu item titles. |news.menu.abbreviate.length|22|The maximum length for abbreviated menu item titles.
|=== |===
==== Email and SMTP configuration ==== Email and SMTP
[cols="1,1,3", options="header"] [cols="1,1,3", options="header"]
.SMTP configuration .SMTP configuration
......
...@@ -51,7 +51,7 @@ building the project. The zip can be found in target/ directory. ...@@ -51,7 +51,7 @@ building the project. The zip can be found in target/ directory.
[[configureJetty]] [[configureJetty]]
=== Install *genesys2-server* and configure Jetty === Install webapp and configure Jetty
Unpack `genesys2-server-{projectVersion}-jetty.zip` archive and move its contents into the jetty directory, Unpack `genesys2-server-{projectVersion}-jetty.zip` archive and move its contents into the jetty directory,
next to existing `demo-base` and `webapps` directories. next to existing `demo-base` and `webapps` directories.
......
[[chApiAccession]]
== 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.
[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_.
. 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"
Managing crop data in Genesys is done through methods available in */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:
include::{snippets}/crop-list/curl-request.adoc[]
The result is a JSON array of all crops in Genesys:
[source,json,linenums]
----
[{
"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
=== Retrieving crop data
The crop details are retrievable with a HTTP GET method 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:
[cols="1,1,2", options="header"]
.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.
.Maize taxonomic rules
include::{snippets}/crop-rules-list/curl-request.adoc[]
[source,json,linenums]
----
[{
"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.
==== 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_).
=== Registering a new crop
To create a new crop, a JSON with the following data must be submitted:
[source,json,linenums]
----
{
"shortName": "maize",
"name": "Maize",
"description": "Crop description in EN"
}
----
[cols="1,1,2", options="header"]
.Minimum required data to register a crop
include::{snippets}/crop-create/request-fields.adoc[]
The response is a single crop record as stored on the server.
==== `curl` example
include::{snippets}/crop-create/curl-request.adoc[]
=== 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`:
[source,json,linenums]
----
[{
"included": true,
"genus": "Triticum"
}, {
"included": true,
"genus": "Aegilops"
}]
----
.Setting new taxonomic rules for the selected crop
include::{snippets}/crop-rules-update/curl-request.adoc[]
[cols="1,1,2", options="header"]
.Taxonomic rule fields
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}`.
This will remove the crop and crop rules from the system.
.Deleting a crop
include::{snippets}/crop-delete/curl-request.adoc[]
== Managing Passport Data
Accession records are *upserted*, meaning that when the matching accession record
. exists, it will be updated
. 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.
TIP: If you want to clear or un-set a value, upsert it as *null*.
`curl` Call
And this thing HTTP request
include::{snippets}/crop-create/http-request.adoc[]
Request fields
include::{snippets}/crop-create/request-fields.adoc[Kaboom]
HTTP Response
include::{snippets}/crop-create/http-response.adoc[]
Response fields
include::{snippets}/crop-create/response-fields.adoc[]
\ No newline at end of file
[[chSecurityModel]]
== Security model
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.
[[chOAuth]]
== Security and OAuth
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].
.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
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.
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.
[cols="1,2"]
.Client ID and Secret for OOB
|===
|Client ID
|`dLCiR.MzwkNha18ImEcw0ADli0@sandbox.genesys-pgr.org`
|Client Secret
|`wGmRAhVplWLEVWlqiMT712PMnaqOa8FN`
|===
=== Obtaining the access token
Most OAuth libraries, including https://bitbucket.org/genesys2/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.
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:
[source,json]
----
{
"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:
[source,http]
----
Authorization: Bearer OAUTH-ACCESS-TOKEN
----
as `curl` parameter:
[source,bash]
----
curl -H "Authorization: Bearer OAUTH-TOKEN" https://sandbox.genesys-pgr.org
----
or include it in the request URL as a query string parameter:
[source,bash]
----
$ curl 'https://sandbox.genesys-pgr.org/api/v0/me?access_token=OAUTH-ACCESS-TOKEN'
----
== Client errors
The API returns descriptive information in the response body about why the request failed to execute.
=== 401 Unauthorized
*401 Unauthorized* indicates that the request did not include valid authentication data. Check your <<chOAtoken, OAuth access token>>.
[source,http]
----
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"}
----
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment