Commit 31e8a7d3 authored by Matija Obreza's avatar Matija Obreza

Merge branch 'basic-brapi-implementation' into 'master'

Basic brapi implementation

Closes #9 and #6

See merge request !5
parents 48f012a0 9097c967
Genesys BrAPI reference manual
==============================
March 2017: Documentation commit {buildNumber}
:revnumber: {projectVersion}
:doctype: book
:toc: left
:toclevels: 5
:icons: font
:numbered:
:source-highlighter: pygments
:pygments-css: class
:pygments-linenums-mode: table
Genesys implements basic <<brapiv1, BrAPI v1 specification>>
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::brapi/auth.adoc[]
include::brapi/crops.adoc[]
include::brapi/germplasm.adoc[]
[bibliography]
- [[brapiv1]] http://docs.brapi.apiary.io/. Retrieved March 2017.
[[chAuth]]
== Authentication
All BrAPI requests can be made anonymously, without providing the OAuth2
*Bearer: <TOKEN>* authentication header.
=== Login
Genesys does not support the `/login` endpoint.
=== Logout
Genesys does not support the `/logout` endpoint.
[[chGermplasm]]
== Crops
*/brapi/v1/crops* endpoint allows for retrieving the list of
Genesys crops.
include::{snippets}/brapi-crops/curl-request.adoc[]
==== Request parameters
include::{snippets}/brapi-crops/request-parameters.adoc[]
==== Server response
Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums]
----
{
"metadata": {
"status": [], <1>
"datafiles": [], <2>
"pagination": { <3>
"pageSize": 50,
"currentPage": 0,
"totalCount": 28,
"totalPages": 1
}
},
"result": <4>
["banana", "barley", "beans", "breadfruit", "cassava", "chickpea", "coconut", "cowpea", "potato", "fababean", "fingermillet", "grasspea", "lentil", "maize", "pearlmillet", "pigeonpea", "rice", "sorghum", "sweetpotato", "taro", "wheat", "yam", "sunflower", "tomato", "eggplant", "lettuce", "apple", "forages"]
}
----
<1> Request status
<2> Data files generated by the request
<3> Pagination data
<4> Result
include::{snippets}/brapi-crops/response-fields.adoc[]
[[chGermplasm]]
== Germplasm
=== Germplasm search
*/brapi/v1/germplasm-search* endpoint allows for retrieving accession data from
Genesys.
include::{snippets}/brapi-germplasm-search/curl-request.adoc[]
==== Request parameters
include::{snippets}/brapi-germplasm-search/request-parameters.adoc[]
==== Server response
Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums]
----
{
"metadata": {
"status": [],
"datafiles": [],
"pagination": {
"pageSize": 2,
"currentPage": 2,
"totalCount": 3637680,
"totalPages": 1818840
}
},
"result": <1> [{
"defaultDisplayName": "DJUG 16",
"germplasmPUI": null,
"pedigree": null,
"seedSource": null,
"synonyms": ["DJUG 16"],
"commonCropName": null,
"genus": "Juglans",
"species": "californica",
"subtaxa": null,
"subtAuthor": null,
"germplasmDbId": "ac5d4de4-dc7d-487b-b11f-b4b4c8b7c045",
"accessionNumber": "DJUG 16",
"germplasmName": "DJUG 16",
"instituteCode": "USA390",
"instituteName": "Botany Department, University of California",
"biologicalStatusOfAccessionCode": 999,
"countryOfOriginCode": "USA",
"typeOfGermplasmStorageCode": [],
"speciesAuthority": null,
"acquisitionDate": "19830923"
}, {
"defaultDisplayName": "NSL 18",
"germplasmPUI": null,
"pedigree": null,
"seedSource": null,
"synonyms": ["PIRA NARANJA", "NSL 18", "PIRA NARANJA"],
"commonCropName": "maize",
"genus": "Zea",
"species": "mays",
"subtaxa": "subsp. mays",
"subtAuthor": null,
"germplasmDbId": "86131120-782b-4108-afde-82de3ae008a4",
"accessionNumber": "NSL 18",
"germplasmName": "NSL 18",
"instituteCode": "USA020",
"instituteName": "North Central Regional Plant Introduction Station, USDA-ARS, NCRPIS",
"biologicalStatusOfAccessionCode": 300,
"countryOfOriginCode": null,
"typeOfGermplasmStorageCode": [],
"speciesAuthority": "L.",
"acquisitionDate": "195905--"
}]
}
----
<1> Array containing matching Germplasm records
include::{snippets}/brapi-germplasm-search/response-fields.adoc[]
=== Germplasm by ID
*/brapi/v1/germplasm/{germplasmID}* endpoint allows for retrieving accession data from
Genesys.
include::{snippets}/brapi-germplasm/curl-request.adoc[]
==== Path parameters
include::{snippets}/brapi-germplasm/path-parameters.adoc[]
==== Server response
[source,json,linenums]
----
{
"metadata": {
"status": [],
"datafiles": [],
"pagination": {
"pageSize": 0,
"currentPage": 0,
"totalCount": 0,
"totalPages": 0
}
},
"result": {
"defaultDisplayName": "TCc-8104",
"germplasmPUI": null,
"pedigree": null,
"seedSource": null,
"synonyms": null,
"commonCropName": "pigeonpea",
"genus": "Cajanus",
"species": "cajan",
"subtaxa": null,
"subtAuthor": null,
"germplasmDbId": "cd8c1217-4503-4859-813b-32251f0c8eba",
"accessionNumber": "TCc-8104",
"germplasmName": "TCc-8104",
"instituteCode": "NGA039",
"instituteName": "International Institute of Tropical Agriculture",
"biologicalStatusOfAccessionCode": null,
"countryOfOriginCode": "SLE",
"typeOfGermplasmStorageCode": [],
"speciesAuthority": null,
"acquisitionDate": null
}
}
----
include::{snippets}/brapi-germplasm/response-fields.adoc[]
/*
* Copyright 2017 Global Crop Diversity Trust
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.genesys2.brapi.model;
import java.util.ArrayList;
import java.util.List;
import org.springframework.data.domain.Page;
/**
* BrAPI v1 response structure
*
* @author Matija Obreza
*/
public class BrAPIResponse<T> {
public Metadata metadata = new Metadata();
public Object result;
public BrAPIResponse() {
}
public BrAPIResponse(Page<T> results) {
this.result = results.getContent();
this.metadata.pagination.update(results);
}
public BrAPIResponse(Throwable exception) {
this.metadata.status.add(new Status(exception.getMessage()));
}
public BrAPIResponse(T result) {
this.result = result;
}
/**
* Response metadata
*/
public static class Metadata {
/// If no status is reported, an empty list should be returned
public List<Status> status = new ArrayList<>();
/// The datafiles key contains a list of strings. The empty list should be returned if no datafiles are present.
public List<String> datafiles = new ArrayList<>();
/// For paginated results
public Pagination pagination = new Pagination();
}
/**
* The status object contains a list of objects with the keys "code" and "message".
*/
public static class Status {
public Status(String message) {
this.message = message;
}
public Status(String code, String message) {
this.code = code;
this.message = message;
}
public String code;
public String message;
}
/**
* BrAPI pagination
*/
public static class Pagination {
public int pageSize = 0;
public int currentPage = 0;
public long totalCount = 0;
public int totalPages = 0;
/**
* Update this Pagination with information from Spring's Page<?>
*
* @param page
*/
public void update(Page<?> page) {
this.pageSize = page.getSize();
this.currentPage = page.getNumber();
this.totalPages = page.getTotalPages();
this.totalCount = page.getTotalElements();
}
}
}
package org.genesys2.brapi.model;
import java.io.Serializable;
import java.util.List;
import java.util.UUID;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* Germplasm as in http://docs.brapi.apiary.io/#reference/germplasm/germplasm-search-by-germplasmdbid
*
* @author Matija Obreza
*/
public class Germplasm implements Serializable {
private static final long serialVersionUID = 1L;
/// Internal db identifier Y
@JsonProperty("germplasmDbId")
private UUID uuid;
/// A string that can be displayed to the user Y
private String defaultDisplayName;
/// This is the unique identifier for accessions within a genebank, and is assigned when a sample is entered into
/// the genebank collection
@JsonProperty("accessionNumber")
private String acceNumb;
/// Name of the germplasm. It can be the prefered name and does not have to be unique
@JsonProperty("germplasmName")
private String acceName;
/// Permanent identifier (e.g. URI, DOI, LSID)
private String germplasmPUI;
/// Cross name with optional selection history.
private String pedigree;
/// Seedlot identifier
private String seedSource;
/// List of other germplasm name
private List<String> synonyms;
/// Common name for the crop (e.g. wheat, rice, maize, cassava, banana)
private String commonCropName;
/// [MCPD] Institute that has bred the material. Note: The code may consist of the 3-letter ISO 3166 country code of
/// the country where the institute is located plus a number (e.g. COL001) as recommended by FAO WIEWS Y
@JsonProperty("instituteCode")
private String instCode;
/// [MCPD] Name of the institute (or person) that bred the material.
@JsonProperty("instituteName")
private String instName;
/// [MCPD] 400) Breeding/research material 410) Breeder's line 411) Synthetic population 412) Hybrid 413) Founder
/// stock/base population 414) Inbred line (parent of hybrid cultivar) 415) Segregating population 416) Clonal
/// selection 420) Genetic stock 421) Mutant (e.g. induced/insertion mutants, tilling populations) 422) Cytogenetic
/// stocks 423) Other genetic stocks (e.g. mapping populations)500) Advanced or improved cultivar (conventional
/// breeding methods) 600) GMO (by genetic engineering) 999) Other
@JsonProperty("biologicalStatusOfAccessionCode")
private Integer sampStat;
/// [MCPD] 3-letter ISO 3166-1 code of the country in which the sample was bred or selected (breeding lines, GMOs,
/// segregating populations, hybrids, modern cultivars, etc.).
@JsonProperty("countryOfOriginCode")
private String origCty;
/// [MCPD] If germplasm is maintained under different types of storage, multiple choices are allowed. 10) Seed
/// collection 11) Short term 12) Medium term 13) Long term 20) Field collection 30) In vitro collection 40)
/// Cryopreserved collection 50) DNA collection 99) Other (elaborate in REMARKS field)
@JsonProperty("typeOfGermplasmStorageCode")
private List<Integer> storage;
/// [MCPD] Genus name for taxon. Initial uppercase letter required.
private String genus;
/// [MCPD] Specific epithet portion of the scientific name in lowercase letters.
private String species;
/// [MCPD]
@JsonProperty("speciesAuthority")
private String spAuthor;
/// [MCPD] Subtaxon can be used to store any additional taxonomic identifier. The following abbreviations are
/// allowed: ‘subsp.’ (for subspecies); ‘convar.’ (for convariety); ‘var.’ (for variety); ‘f.’ (for form); ‘Group’
/// (for ‘cultivar group’).
private String subtaxa;
private String subtAuthor;
/**
* [MCPD] code of the donor institute and Identifier assigned to an accession by the donor, and permanent
* identifier.
*/
/// donors array of object
/// [MCPD] Date on which the accession entered the collection 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 zero].
@JsonProperty("acquisitionDate")
private String acqDate;
/**
* @return the uuid
*/
public UUID getUuid() {
return uuid;
}
/**
* @param uuid the uuid to set
*/
public void setUuid(UUID uuid) {
this.uuid = uuid;
}
/**
* @return the defaultDisplayName
*/
public String getDefaultDisplayName() {
return defaultDisplayName;
}
/**
* @param defaultDisplayName the defaultDisplayName to set
*/
public void setDefaultDisplayName(String defaultDisplayName) {
this.defaultDisplayName = defaultDisplayName;
}
/**
* @return the acceNumb
*/
public String getAcceNumb() {
return acceNumb;
}
/**
* @param acceNumb the acceNumb to set
*/
public void setAcceNumb(String acceNumb) {
this.acceNumb = acceNumb;
}
/**
* @return the acceName
*/
public String getAcceName() {
return acceName;
}
/**
* @param acceName the acceName to set
*/
public void setAcceName(String acceName) {
this.acceName = acceName;
}
/**
* @return the germplasmPUI
*/
public String getGermplasmPUI() {
return germplasmPUI;
}
/**
* @param germplasmPUI the germplasmPUI to set
*/
public void setGermplasmPUI(String germplasmPUI) {
this.germplasmPUI = germplasmPUI;
}
/**
* @return the pedigree
*/
public String getPedigree() {
return pedigree;
}
/**
* @param pedigree the pedigree to set
*/
public void setPedigree(String pedigree) {
this.pedigree = pedigree;
}
/**
* @return the seedSource
*/
public String getSeedSource() {
return seedSource;
}
/**
* @param seedSource the seedSource to set
*/
public void setSeedSource(String seedSource) {
this.seedSource = seedSource;
}
/**
* @return the synonyms
*/
public List<String> getSynonyms() {
return synonyms;
}
/**
* @param synonyms the synonyms to set
*/
public void setSynonyms(List<String> synonyms) {
this.synonyms = synonyms;
}
/**
* @return the commonCropName
*/
public String getCommonCropName() {
return commonCropName;
}
/**
* @param commonCropName the commonCropName to set
*/
public void setCommonCropName(String commonCropName) {
this.commonCropName = commonCropName;
}
/**
* @return the instCode
*/
public String getInstCode() {
return instCode;
}
/**
* @param instCode the instCode to set
*/
public void setInstCode(String instCode) {
this.instCode = instCode;
}
/**
* @return the instName
*/
public String getInstName() {
return instName;
}
/**
* @param instName the instName to set
*/
public void setInstName(String instName) {
this.instName = instName;
}
/**
* @return the sampStat
*/
public Integer getSampStat() {
return sampStat;
}
/**
* @param sampStat the sampStat to set
*/
public void setSampStat(Integer sampStat) {
this.sampStat = sampStat;
}
/**
* @return the origCty
*/
public String getOrigCty() {
return origCty;
}
/**
* @param origCty the origCty to set
*/
public void setOrigCty(String origCty) {
this.origCty = origCty;
}
/**
* @return the storage
*/
public List<Integer> getStorage() {
return storage;
}
/**
* @param storage the storage to set
*/
public void setStorage(List<Integer> storage) {
this.storage = storage;
}
/**
* @return the genus
*/
public String getGenus() {
return genus;
}
/**
* @param genus the genus to set
*/
public void setGenus(String genus) {
this.genus = genus;
}
/**
* @return the species
*/
public String getSpecies() {