Skip to content

GitLab

Commit 03badd60 authored by Matija Obreza's avatar Matija Obreza
Browse files

Updated BrAPI documentation

parent 2f7e1e77
Hide whitespace changes
Inline Side-by-side
Showing with 203 additions and 83 deletions
src/main/asciidoc/brapi.adoc
View file @ 03badd60
......@@ -12,7 +12,7 @@ March 2017: Documentation commit {buildNumber}
:pygments-linenums-mode: table
Genesys implements basic BrAPI v1 specification <<brapiv1>>
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.
......@@ -23,5 +23,6 @@ include::brapi/auth.adoc[]
include::brapi/crops.adoc[]
include::brapi/germplasm.adoc[]
[bibliography]
- [[[brapiv1]]]: http://docs.brapi.apiary.io/
- [[[brapiv1]]] http://docs.brapi.apiary.io/. Retrieved March 2017.
src/main/asciidoc/brapi/crops.adoc
View file @ 03badd60
......@@ -8,10 +8,6 @@ Genesys crops.
include::{snippets}/brapi-crops/curl-request.adoc[]
==== Path parameters
include::{snippets}/brapi-crops/path-parameters.adoc[]
==== Request parameters
include::{snippets}/brapi-crops/request-parameters.adoc[]
......@@ -23,36 +19,23 @@ Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums]
----
{
"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>
"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> 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
<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
View file @ 03badd60
......@@ -11,10 +11,6 @@ Genesys.
include::{snippets}/brapi-germplasm-search/curl-request.adoc[]
==== Path parameters
include::{snippets}/brapi-germplasm-search/path-parameters.adoc[]
==== Request parameters
include::{snippets}/brapi-germplasm-search/request-parameters.adoc[]
......@@ -26,36 +22,116 @@ Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums]
----
{
"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>
"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 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
<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/server/servlet/controller/brapi/CropsController.java
View file @ 03badd60
......@@ -45,7 +45,7 @@ public class CropsController extends BaseBrAPIController {
*/
@RequestMapping(value = "/crops", method = RequestMethod.GET, produces = { MediaType.APPLICATION_JSON_VALUE })
public @ResponseBody BrAPIResponse<String> getGermplasmById(@RequestParam(name = "pageSize", required = false, defaultValue = "50") int pageSize,
@RequestParam(name = "pageSize", required = false, defaultValue = "0") int page) {
@RequestParam(name = "page", required = false, defaultValue = "0") int page) {
return new BrAPIResponse<>(brapiService.getCrops(new PageRequest(Math.max(0, page), Math.min(pageSize, 200))));
}
}
src/main/java/org/genesys2/server/servlet/controller/brapi/GermplasmController.java
View file @ 03badd60
......@@ -53,7 +53,7 @@ public class GermplasmController extends BaseBrAPIController {
*/
@RequestMapping(value = "/germplasm-search", method = { RequestMethod.GET, RequestMethod.POST }, produces = { MediaType.APPLICATION_JSON_VALUE })
public @ResponseBody BrAPIResponse<Germplasm> germplasmSearch(@RequestParam(name = "pageSize", required = false, defaultValue = "50") int pageSize,
@RequestParam(name = "pageSize", required = false, defaultValue = "0") int page, @RequestParam(name = "germplasmName", required = false) String germplasmName,
@RequestParam(name = "page", required = false, defaultValue = "0") int page, @RequestParam(name = "germplasmName", required = false) String germplasmName,
@RequestParam(name = "germplasmPUI", required = false) String germplasmPUI, @RequestParam(name = "germplasmDbId", required = false) UUID germplasmDbId) {
return new BrAPIResponse<>(brapiService.searchGermplasm(germplasmName, germplasmPUI, germplasmDbId, new PageRequest(Math.max(0, page), Math.min(pageSize, 200))));
......
src/test/java/org/genesys2/tests/resttests/docs/BrAPITest.java
View file @ 03badd60
......@@ -19,15 +19,19 @@ package org.genesys2.tests.resttests.docs;
import static org.hamcrest.Matchers.*;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
import static org.springframework.restdocs.request.RequestDocumentation.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.google.common.collect.Lists;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
......@@ -91,27 +95,83 @@ public class BrAPITest extends AbstractRestTest {
}
@Test
public void listCropsTest() throws Exception {
public void crops() throws Exception {
LOG.info("Start test-method listCropsTest");
mockMvc.perform(get("/brapi/v1/crops").contentType(MediaType.APPLICATION_JSON))
//
.andExpect(status().isOk()).andExpect(content().contentType(MediaType.APPLICATION_JSON))
//
mockMvc.perform(get("/brapi/v1/crops?page=0&pageSize=2").contentType(MediaType.APPLICATION_JSON)).andExpect(status().isOk()).andExpect(content().contentType(MediaType.APPLICATION_JSON))
// peek
.andDo(r -> {
System.err.println(r.getResponse().getContentAsString());
})
//
.andExpect(jsonPath("$.result", hasSize(greaterThan(0)))).andExpect(jsonPath("$.result[0]", is("maize")))
//
.andExpect(jsonPath("$.metadata", is(notNullValue()))).andExpect(jsonPath("$.metadata.status", hasSize(0)))
.andExpect(jsonPath("$.metadata.datafiles", hasSize(0)))
//
// metadta
.andExpect(jsonPath("$.metadata", is(notNullValue()))).andExpect(jsonPath("$.metadata.status", hasSize(0))).andExpect(jsonPath("$.metadata.datafiles", hasSize(0)))
.andExpect(jsonPath("$.metadata.pagination", is(not(nullValue()))))
// .andExpect(jsonPath("$[0].i18n", is(nullValue()))).andExpect(jsonPath("$[0].name", is("Maize"))).andExpect(jsonPath("$[0].description", is("Crop description in EN")))
.andDo(document("brapi-crops"));
// result array
.andExpect(jsonPath("$.result", hasSize(greaterThan(0)))).andExpect(jsonPath("$.result[0]", is("maize")))
// .andExpect(jsonPath("$[0].i18n", is(nullValue()))).andExpect(jsonPath("$[0].name",
// is("Maize"))).andExpect(jsonPath("$[0].description", is("Crop description in EN")))
.andDo(document("brapi-crops",
// querystring parameters
requestParameters(parameterWithName("pageSize").description("Requested page size. Default is 50 records per page."),
parameterWithName("page").description("The page to retrieve (0-based)")),
// request fields
responseFields(fieldWithPath("metadata").description("BrAPI v1 reponse metadata"), fieldWithPath("result").description("List of Genesys crop names"))));
LOG.info("Test listCropsTest passed");
}
@Test
public void germplasmSearch() throws Exception {
mockMvc.perform(get("/brapi/v1/germplasm-search?page=0&pageSize=2&germplasmName=&germplasmDbId=&germplasmPUI=").contentType(MediaType.APPLICATION_JSON)).andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_JSON))
// peek
.andDo(r -> {
System.err.println(r.getResponse().getContentAsString());
})
// metadta
.andExpect(jsonPath("$.metadata", is(notNullValue()))).andExpect(jsonPath("$.metadata.status", hasSize(0))).andExpect(jsonPath("$.metadata.datafiles", hasSize(0)))
.andExpect(jsonPath("$.metadata.pagination", is(not(nullValue()))))
// result array
.andExpect(jsonPath("$.result", is(notNullValue())))
// .andExpect(jsonPath("$[0].i18n", is(nullValue()))).andExpect(jsonPath("$[0].name",
// is("Maize"))).andExpect(jsonPath("$[0].description", is("Crop description in EN")))
.andDo(document("brapi-germplasm-search",
// querystring parameters
requestParameters(parameterWithName("pageSize").description("Requested page size. Default is 50 records per page."),
parameterWithName("page").description("The page to retrieve (0-based)"),
// specific
parameterWithName("germplasmName").description("Return accessions where ACCENUMB starts with provided value"),
parameterWithName("germplasmPUI").description("Return accessions where PUID matches provided value"),
parameterWithName("germplasmDbId").description("Return accessions where UUID matches provided value")),
// response fields
responseFields(fieldWithPath("metadata").description("BrAPI v1 reponse metadata"), fieldWithPath("result").description("List of BrAPI Germplasm records"))));
}
@Test
public void germplasm() throws Exception {
mockMvc.perform(get("/brapi/v1/germplasm/{germplasmID}", "cd8c1217-4503-4859-813b-32251f0c8eba").contentType(MediaType.APPLICATION_JSON))
// response
// .andExpect(status().isOk()).andExpect(content().contentType(MediaType.APPLICATION_JSON))
// peek
.andDo(r -> {
System.err.println(r.getResponse().getContentAsString());
})
// metadta
.andExpect(jsonPath("$.metadata", is(notNullValue()))).andExpect(jsonPath("$.metadata.status", not(nullValue()))).andExpect(jsonPath("$.metadata.datafiles", hasSize(0)))
.andExpect(jsonPath("$.metadata.pagination", is(not(nullValue()))))
// result array
// .andExpect(jsonPath("$.result", is(notNullValue())))
// .andExpect(jsonPath("$[0].i18n", is(nullValue()))).andExpect(jsonPath("$[0].name",
// is("Maize"))).andExpect(jsonPath("$[0].description", is("Crop description in EN")))
.andDo(document("brapi-germplasm",
// path parameters
pathParameters(parameterWithName("germplasmID").description("UUID of accession record in Genesys")),
// response fields
responseFields(fieldWithPath("metadata").description("BrAPI v1 reponse metadata"), fieldWithPath("result").description("Single BrAPI Germplasm record"))));
}
}
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