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

Updated BrAPI documentation

parent 2f7e1e77
...@@ -12,7 +12,7 @@ March 2017: Documentation commit {buildNumber} ...@@ -12,7 +12,7 @@ March 2017: Documentation commit {buildNumber}
:pygments-linenums-mode: table :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 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. 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[] ...@@ -23,5 +23,6 @@ include::brapi/auth.adoc[]
include::brapi/crops.adoc[] include::brapi/crops.adoc[]
include::brapi/germplasm.adoc[] include::brapi/germplasm.adoc[]
[bibliography] [bibliography]
- [[[brapiv1]]]: http://docs.brapi.apiary.io/ - [[[brapiv1]]] http://docs.brapi.apiary.io/. Retrieved March 2017.
...@@ -8,10 +8,6 @@ Genesys crops. ...@@ -8,10 +8,6 @@ Genesys crops.
include::{snippets}/brapi-crops/curl-request.adoc[] include::{snippets}/brapi-crops/curl-request.adoc[]
==== Path parameters
include::{snippets}/brapi-crops/path-parameters.adoc[]
==== Request parameters ==== Request parameters
include::{snippets}/brapi-crops/request-parameters.adoc[] include::{snippets}/brapi-crops/request-parameters.adoc[]
...@@ -23,36 +19,23 @@ Genesys returns the standard BrAPI Germplasm response: ...@@ -23,36 +19,23 @@ Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums] [source,json,linenums]
---- ----
{ {
"content": [{ "metadata": {
"uuid": "4422e87e-52fe-38ef-b04a-079e663dd3da", "status": [], <1>
"version": 0, "datafiles": [], <2>
"instCode": "XXX001", "pagination": { <3>
"instEmail": "institute@localhost", "pageSize": 50,
"state": 0, "currentPage": 0,
"createdDate": null, "totalCount": 28,
"lastModifiedDate": null, "totalPages": 1
"lastReminderDate": null }
}], <1> },
"last": true, "result": <4>
"totalElements": 1, <2> ["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"]
"totalPages": 1, <3>
"size": 10, <4>
"number": 0,
"sort": [{
"direction": "DESC",
"property": "createdDate",
"ignoreCase": false,
"nullHandling": "NATIVE",
"ascending": false
}],
"first": true,
"numberOfElements": 1 <5>
} }
---- ----
<1> Array containing request information <1> Request status
<2> Number of elements in the Genesys database <2> Data files generated by the request
<3> Number of pages <3> Pagination data
<4> Page size <4> Result
<5> Number of elements in the `content` array
include::{snippets}/brapi-crops/response-fields.adoc[] include::{snippets}/brapi-crops/response-fields.adoc[]
...@@ -11,10 +11,6 @@ Genesys. ...@@ -11,10 +11,6 @@ Genesys.
include::{snippets}/brapi-germplasm-search/curl-request.adoc[] include::{snippets}/brapi-germplasm-search/curl-request.adoc[]
==== Path parameters
include::{snippets}/brapi-germplasm-search/path-parameters.adoc[]
==== Request parameters ==== Request parameters
include::{snippets}/brapi-germplasm-search/request-parameters.adoc[] include::{snippets}/brapi-germplasm-search/request-parameters.adoc[]
...@@ -26,36 +22,116 @@ Genesys returns the standard BrAPI Germplasm response: ...@@ -26,36 +22,116 @@ Genesys returns the standard BrAPI Germplasm response:
[source,json,linenums] [source,json,linenums]
---- ----
{ {
"content": [{ "metadata": {
"uuid": "4422e87e-52fe-38ef-b04a-079e663dd3da", "status": [],
"version": 0, "datafiles": [],
"instCode": "XXX001", "pagination": {
"instEmail": "institute@localhost", "pageSize": 2,
"state": 0, "currentPage": 2,
"createdDate": null, "totalCount": 3637680,
"lastModifiedDate": null, "totalPages": 1818840
"lastReminderDate": null }
}], <1> },
"last": true, "result": <1> [{
"totalElements": 1, <2> "defaultDisplayName": "DJUG 16",
"totalPages": 1, <3> "germplasmPUI": null,
"size": 10, <4> "pedigree": null,
"number": 0, "seedSource": null,
"sort": [{ "synonyms": ["DJUG 16"],
"direction": "DESC", "commonCropName": null,
"property": "createdDate", "genus": "Juglans",
"ignoreCase": false, "species": "californica",
"nullHandling": "NATIVE", "subtaxa": null,
"ascending": false "subtAuthor": null,
}], "germplasmDbId": "ac5d4de4-dc7d-487b-b11f-b4b4c8b7c045",
"first": true, "accessionNumber": "DJUG 16",
"numberOfElements": 1 <5> "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 <1> Array containing matching Germplasm records
<2> Number of elements in the Genesys database
<3> Number of pages
<4> Page size
<5> Number of elements in the `content` array
include::{snippets}/brapi-germplasm-search/response-fields.adoc[] 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[]
...@@ -45,7 +45,7 @@ public class CropsController extends BaseBrAPIController { ...@@ -45,7 +45,7 @@ public class CropsController extends BaseBrAPIController {
*/ */
@RequestMapping(value = "/crops", method = RequestMethod.GET, produces = { MediaType.APPLICATION_JSON_VALUE }) @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, 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)))); return new BrAPIResponse<>(brapiService.getCrops(new PageRequest(Math.max(0, page), Math.min(pageSize, 200))));
} }
} }
...@@ -53,7 +53,7 @@ public class GermplasmController extends BaseBrAPIController { ...@@ -53,7 +53,7 @@ public class GermplasmController extends BaseBrAPIController {
*/ */
@RequestMapping(value = "/germplasm-search", method = { RequestMethod.GET, RequestMethod.POST }, produces = { MediaType.APPLICATION_JSON_VALUE }) @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, 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) { @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)))); return new BrAPIResponse<>(brapiService.searchGermplasm(germplasmName, germplasmPUI, germplasmDbId, new PageRequest(Math.max(0, page), Math.min(pageSize, 200))));
......
...@@ -19,15 +19,19 @@ package org.genesys2.tests.resttests.docs; ...@@ -19,15 +19,19 @@ package org.genesys2.tests.resttests.docs;
import static org.hamcrest.Matchers.*; import static org.hamcrest.Matchers.*;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*; import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*; 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.test.web.servlet.result.MockMvcResultMatchers.*;
import static org.springframework.restdocs.request.RequestDocumentation.*;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.List; import java.util.List;
import java.util.UUID;
import com.fasterxml.jackson.annotation.JsonInclude.Include; import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.databind.DeserializationFeature; import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature; import com.fasterxml.jackson.databind.SerializationFeature;
import com.google.common.collect.Lists;
import org.apache.commons.logging.Log; import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory; import org.apache.commons.logging.LogFactory;
...@@ -91,27 +95,83 @@ public class BrAPITest extends AbstractRestTest { ...@@ -91,27 +95,83 @@ public class BrAPITest extends AbstractRestTest {
} }
@Test @Test
public void listCropsTest() throws Exception { public void crops() throws Exception {
LOG.info("Start test-method listCropsTest"); LOG.info("Start test-method listCropsTest");
mockMvc.perform(get("/brapi/v1/crops").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
.andExpect(status().isOk()).andExpect(content().contentType(MediaType.APPLICATION_JSON))
//
.andDo(r -> { .andDo(r -> {
System.err.println(r.getResponse().getContentAsString()); System.err.println(r.getResponse().getContentAsString());
}) })
// // metadta
.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)))
//
.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("$.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"))) // result array
.andDo(document("brapi-crops")); .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"); 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