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

Basic brapi implementation

Closes #9 and #6

See merge request !5

src/main/asciidoc/brapi.adoc

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

src/main/asciidoc/brapi/auth.adoc

+[[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.

src/main/asciidoc/brapi/crops.adoc

+[[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[]

src/main/asciidoc/brapi/germplasm.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[]

src/main/java/org/genesys2/brapi/model/BrAPIResponse.java

+/*
+ * 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();
+		}
+	}
+}

src/main/java/org/genesys2/brapi/model/Germplasm.java

+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() {
+