Merge pull request #127 from plantbreeding/issue-23

Consistent pagination documentation

Specification/Calls/Calls.md

@@ -20,18 +20,18 @@ Used by: Flapjack
 
 ### Call search [GET]
 + Parameters
-    + datatype (optional, string, `tsv`) ... The data type supported by the call
-    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
-    + page (optional, integer, `10`) ... Which result page is requested
+   + datatype (optional, string, `tsv`) ... The data type supported by the call
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 + Response 200 (application/json)
 
         {
             "metadata": {
                 "pagination" : {
-                "totalCount" : 7,
+                "totalCount" : 8,
                 "currentPage" : 0,
                 "totalPages" : 1,
-                "pageSize" : "10"
+                "pageSize" : 1000
             },
             "datafiles" : []
             },

Specification/Crops/ListCrops.md

@@ -1,18 +1,21 @@
-## List supported crops [/brapi/v1/crops]
+## List supported crops [/brapi/v1/crops?pageSize={pageSize}&page={page}]
 Scope: CORE.
 Status: ACCEPTED.
 
 ### List supported crops [GET]
++ Parameters
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
         {
             "metadata": {
                 "pagination": {
-                    "pageSize": 2,
+                    "pageSize": 1000,
                     "currentPage": 0,
-                    "totalCount": 100,
-                    "totalPages": 50
+                    "totalCount": 3,
+                    "totalPages": 1
                 },
                 "status" : [],
                 "datafiles": []

Specification/GenomeMaps/GenomeMapData.md

@@ -13,16 +13,19 @@ markers ordered by linkageGroup and position
 + Parameters
    + mapDbId (required, string, `6`) ... unique id of the map
    + linkageGroupId (optional, string, `123`) ... the linkage group id
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
+
 
 + Response 200 (application/json)
 
         {
             "metadata" : { 
                 "pagination" : { 
-                    "pageSize": 30, 
-                    "currentPage": 2, 
-                    "totalCount": 40, 
-                    "totalPages":2 
+                    "pageSize": 1000, 
+                    "currentPage": 0, 
+                    "totalCount": 2, 
+                    "totalPages": 1 
                 },
                 "status": [],
                 "datafiles": []

Specification/GenomeMaps/GenomeMapDataByRangeOnLinkageGroup.md

@@ -9,16 +9,19 @@ markers ordered by linkageGroup and position
    + linkageGroupId (required, string)
    + min (optional) ... minimum position on linkage group
    + max (optional) ... maximumn position on linkage group
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
+
 
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination" : {             
-                    "pageSize": 30, 
-                    "currentPage": 2, 
-                    "totalCount": 40, 
-                    "totalPages":2 
+                    "pageSize": 1000, 
+                    "currentPage": 0, 
+                    "totalCount": 2, 
+                    "totalPages": 1 
                 },
                 "status" : [],
                 "datafiles": []

Specification/GenomeMaps/ListOfGenomeMaps.md

@@ -11,16 +11,20 @@ Get list of maps
 do we need list of parents and specify mapping population?
 
 ### Get list of maps [GET]
++ Parameters
+   + species (optional, string, ``) ... Species
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination" : {
-                    "pageSize": 30,
-                    "currentPage": 2,
-                    "totalCount": 40,
-                    "totalPages": 2
+                    "pageSize": 1000,
+                    "currentPage": 0,
+                    "totalCount": 2,
+                    "totalPages": 1
                 }
                 "status" : [],
                 "datafiles": []

Specification/Germplasm/GermplasmSearchGET.md

@@ -50,7 +50,8 @@ Use GET when parameter size is less than 2K bytes.
    + germplasmDbId (optional, string, `986`) ... Internal database identifier
    + germplasmName (optional, string, `Pah`, `Pahang`) ... Name of the germplasm
    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
-   + page (optional, integer, `10`) ... Which result page is requested
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
+
 
 + Response 200 (application/json)
 
@@ -59,8 +60,8 @@ Use GET when parameter size is less than 2K bytes.
                 "status": [],
                 "datafiles": [],
                 "pagination": {
-                    "pageSize": 10,
-                    "currentPage": 1,
+                    "pageSize": 1000,
+                    "currentPage": 0,
                     "totalCount": 2,
                     "totalPages": 1
                 }

Specification/Germplasm/GermplasmSearchPOST.md

@@ -22,10 +22,10 @@ Use POST for large queries (>2K bytes).
                 "status": [],
                 "datafiles": [],
                 "pagination": {
-                    "pageSize": 10,
+                    "pageSize": 100,
                     "currentPage": 1,
-                    "totalCount": 2,
-                    "totalPages": 1
+                    "totalCount": 102,
+                    "totalPages": 2
                 }
             },
             "result": {

Specification/GermplasmAttributes/GermplasmAttributeValuesByGermplasmDbId.md

@@ -1,4 +1,4 @@
-## Germplasm attribute values by germplasmDbId [/brapi/v1/germplasm/{germplasmDbId}/attributes?attributeList={attributeDbId},{attributeDbId}&pageSize=&page=]
+## Germplasm attribute values by germplasmDbId [/brapi/v1/germplasm/{germplasmDbId}/attributes?attributeList={attributeDbId},{attributeDbId}&pageSize={pageSize}&page={page}]
 
 Status: ACCEPTED.]
 
@@ -7,17 +7,17 @@ Values for all attributes by default.
 + Parameters
     + germplasmDbId (required, string, `993`) ... The germplasm characterized
     + attributeDbId (optional, string, `1`) ... Restrict the response to only the listed attributes.
-    + pageSize (optional, integer, `10000`) ... the number of attributes to return in one request, defaults to 1000.
-    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The first page is 1, not 0.
+    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+    + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination": {
-                    "pageSize": 10,
-                    "currentPage": 1,
-                    "totalCount": 10,
+                    "pageSize": 1000,
+                    "currentPage": 0,
+                    "totalCount": 1,
                     "totalPages": 1
                 },
                 "status": [],

Specification/GermplasmAttributes/ListAttributeCategories.md

@@ -1,12 +1,12 @@
-## List attribute categories [/brapi/v1/attributes/categories?pageSize=10&page=2] 
+## List attribute categories [/brapi/v1/attributes/categories?pageSize={pageSize}&page={page}] 
 Scope: OTHER. Status: ACCEPTED.
 Implementation target date: PAG2016
 
 ### Germplasm attribute categories [GET]
 List all available attribute categories.
 + Parameters
-    + pageSize (optional, integer, `10000`) Number of attributes to return in one response
-    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The first page is 1, not 0.
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
@@ -15,7 +15,7 @@ List all available attribute categories.
                 "pagination": {
                     "pageSize": 10,
                     "currentPage": 1,
-                    "totalCount": 10,
+                    "totalCount": 2,
                     "totalPages": 1
                 },
                 "status": [],

Specification/GermplasmAttributes/ListAttributesByAttributeCategoryDbId.md

@@ -1,4 +1,4 @@
-## List attributes available [/brapi/v1/attributes?attributeCategoryDbId=2]
+## List attributes available [/brapi/v1/attributes?attributeCategoryDbId={attributeCategoryDbId}&pageSize={pageSize}&page={page}]
 Scope: OTHER. Status: ACCEPTED.
 Implementation target date: PAG2016
 
@@ -17,16 +17,19 @@ List available attributes.
 |datatype|string|e.g. Categorical, Numeric, Boolean||
 |values|array of string|array of all possible values for this attribute|Y|
 + Parameters
-    + attributeCategoryDbId (optional, string, `2`) ... filter for kind of attributes
+   + attributeCategoryDbId (optional, string, `2`) ... filter for kind of attributes
+   + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+   + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
+
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination": {
-                    "pageSize": 10,
-                    "currentPage": 1,
-                    "totalCount": 10000,
-                    "totalPages": 1000
+                    "pageSize": 1000,
+                    "currentPage": 0,
+                    "totalCount": 1,
+                    "totalPages": 1
                 },
                 "status": [],
                 "datafiles": []

Specification/Locations/ListLocations.md

@@ -1,4 +1,4 @@
-## List Locations [/brapi/v1/locations?locationType={locationType}]
+## List Locations [/brapi/v1/locations?locationType={locationType}&pageSize={pageSize}&page={page}]
 
 Implemented by: Germinate
 
@@ -13,18 +13,18 @@ Get a list of locations.
 
 + Parameters
     + locationType (optional, string, `Breeding Locations`) - Filter by location type specified.
-    + page (optional, integer, `2282`) - request a specific response page
-    + pageSize (optional, integer, `5000`) - request a non-default page size (1000 is default)
+    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+    + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
         {
             "metadata": {
                 "pagination": { 
-                    "currentPage": 1,
-                    "pageSize": 2,
-                    "totalCount": 100,
-                    "totalPages": 50
+                    "currentPage": 0,
+                    "pageSize": 1000,
+                    "totalCount": 2,
+                    "totalPages": 1
                 },
                 "status" : [],
                 "datafiles": []

Specification/MarkerProfiles/MarkerProfileAlleleMatrix.md

@@ -25,16 +25,16 @@ This method may support asynchronous processing.
     + expandHomozygotes (optional, boolean, `false`) ... Should homozygotes NOT be collapsed into a single occurence?
     + unknownString (optional, string, `-`) ... The string to use as a representation for missing data or the reserved word "empty_string".
     + sepPhased (optional, string, `|`) ... The string to use as a separator for phased allele calls or the reserved word "empty_string".
-    + sepUnphased (optional, string, `/`) ... The string to use as a separator for unphased allele calls or the reserved word "empty_string".
-    + pageSize (optional, integer, `1000`) ... the number of allele calls reported per response page.
-    + page (optional, integer, `10`) ... the requested response page
+    + sepUnphased (optional, string, `/`) ... The string to use as a separator for unphased allele calls or the reserved word "empty_string".    
+    + pageSize (optional, integer, `1000`) ... The size of the pages to be returned. Default is `1000`.
+    + page (optional, integer, `0`) ... Which result page is requested. The page indexing starts at 0 (the first page is 'page'= 0). Default is `0`.
 
 + Response 200 (application/json)
 
         {
             "metadata": {   
                 "pagination": {
-                    "pageSize": 100,
+                    "pageSize": 1000,
                     "currentPage": 0,
                     "totalCount": 1,
                     "totalPages": 1

Specification/MarkerProfiles/MarkerProfileData.md

@@ -42,16 +42,16 @@ Alphabetically?
    + sepPhased (optional, string, `|`) ... The string to use as a separator for phased allele calls or the reserved word "empty_string".
    + sepUnphased (optional, string, `/`) ... The string to use as a separator for unphased allele calls or the reserved word "empty_string".
    + pageSize (optional, integer, `10000`) ... The number of allele call results (marker/allele pairs) to be returned in the response. If multiple experiments are requested, some responses will contain the last results from one experiment followed by the first results from the next.
-   + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The first page is 1, not 0.
+   + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The page indexing starts at 0 (the first page is 'page'=0)
 
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination": {
-                    "pageSize": 10,
+                    "pageSize": 1000,
                     "currentPage": 0,
-                    "totalCount": 10,
+                    "totalCount": 1,
                     "totalPages": 1
                 },
                 "status": [],

Specification/MarkerProfiles/MarkerProfileSearch.md

@@ -1,4 +1,4 @@
-## Markerprofile search [/brapi/v1/markerprofiles?germplasm={germplasmDbId}&studyDbId={studyDbId}&sample={sampleDbId}&extract={extractDbId}&method={methodDbId}&pageSize=100&page=4]
+## Markerprofile search [/brapi/v1/markerprofiles?germplasm={germplasmDbId}&studyDbId={studyDbId}&sample={sampleDbId}&extract={extractDbId}&method={methodDbId}&pageSize={pageSize}&page={page}]
 Scope: GENOTYPING.
 Status: ACCEPTED.
 
@@ -16,15 +16,15 @@ For the requested Germplasm Id and/or Extract Id, returns the Markerprofile Id a
     + sampleDbId (optional, string, `184`) ... The server's internal id for the SampleDbId
     + extractDbId (optional, string, `84`) ... The server's internal id for the ExtractDbId
     + pageSize (optional, integer, `10000`) ... The number of allele call results (marker/allele pairs) to be returned in the response. If multiple experiments are requested, some responses will contain the last results from one experiment followed by the first results from the next.
-    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The first page is 1, not 0.
+    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The page indexing starts at 0 (the first page is 'page'=0)
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination": {
-                    "pageSize": 10,
+                    "pageSize": 1000,
                     "currentPage": 0,
-                    "totalCount": 10,
+                    "totalCount": 2,
                     "totalPages": 1
                 },
                 "status": [],

Specification/MarkerProfiles/MarkerProfileSearchPost.md

@@ -1,4 +1,4 @@
-## Markerprofile search [/brapi/v1/markerprofiles-search?germplasm={germplasmDbId}&studyDbId={studyDbId}&sample={sampleDbId}&extract={extractDbId}&method={methodDbId}&pageSize=100&page=4]
+## Markerprofile search [/brapi/v1/markerprofiles-search?germplasm={germplasmDbId}&studyDbId={studyDbId}&sample={sampleDbId}&extract={extractDbId}&method={methodDbId}&pageSize={pageSize}&page={page}]
 Scope: GENOTYPING.
 Status: ACCEPTED.
 
@@ -12,15 +12,15 @@ For the requested Germplasm Ids and/or Extract Ids, returns the Markerprofile Id
     + sampleDbId (optional, string, `184`) ... The server's internal id for the SampleDbId
     + extractDbId (optional, string, `84`) ... The server's internal id for the ExtractDbId
     + pageSize (optional, integer, `10000`) ... The number of allele call results (marker/allele pairs) to be returned in the response. If multiple experiments are requested, some responses will contain the last results from one experiment followed by the first results from the next.
-    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The first page is 1, not 0.
+    + page (optional, integer, `1`) ... Required if `pageSize` is given; and requires that `pageSize` be given. The page indexing starts at 0 (the first page is 'page'=0)
 + Response 200 (application/json)
 
         {
             "metadata" : {
                 "pagination": {
-                    "pageSize": 10,
+                    "pageSize": 1000,
                     "currentPage": 0,
-                    "totalCount": 10,
+                    "totalCount": 2,
                     "totalPages": 1
                 },
                 "status": [],

Specification/Markers/MarkerDetailsByMarkerDbId.md

@@ -26,10 +26,10 @@ Implemented By:
         {
             "metadata": {                
                 "pagination": {
-                    "pageSize": 100,
-                    "currentPage": 1,
-                    "totalCount": 1,
-                    "totalPages": 1
+                    "pageSize": 0,
+                    "currentPage": 0,
+                    "totalCount": 0,
+                    "totalPages": 0
                 },
                 "status": [],
                 "datafiles": [],