FORMAT: 1A # BrAPI V1.1 The Breeding API specifies a standard interface for plant phenotype/genotype databases to serve their data to crop breeding applications. It is a shared, open API, to be used by all data providers and data consumers who wish to participate. Initiated in May 2014, it is currently in an actively developing state, so now is the time for potential participants to help shape the specifications to ensure their needs are addressed. For more information, go to brapi.org. ### URL structure API requests are structured as "\/brapi/v1/", where "v1" is the major version number of the API, followed by the command. Example: test.brapi.org/brapi/v1/markerprofiles/2939 To distinguish between multiple databases or crops available from the same server, include the database or crop name as part of the "\" identifier. An arbitrary number of levels can be inserted between the domain name and the crops or brapi level, if needed. Example: test.brapi.org/maize/brapi/v1/markerprofiles/2939 ### Structure of the response object: The return objects are encoded in JSON. The response consists of: + A "metadata" key containing pagination, status, and file information; + A "result" key that can contain: + Arbitrary properties; and/or + A "data" key containing an array of objects of the same type. #### The Metadata Key The metadata key is structured as followed: ```` { "metadata" : { "pagination" : { "totalCount" : 1234, // total number of elements available in the super set (unpaged) "pageSize" : 200, // number of elements in the current returned page "totalPages" : 7, // total number of pages available (total count / requested page size) "currentPage" : 2 // index number of the current returned page }, "status" : [ { "code" : "200", "message" : "Success" },{ "code" : "asynchstatus", "message" : "PENDING" } ], "datafiles" : ["/mnt/local/matrix_01.csv", "/mnt/local/matrix_02.csv"] }, . . . } ```` + **pagination**: The pagination object is applicable only when the payload contains a "data" key. It describes the pagination of the data contained in the "data" array, as a way to identify which subset of data is being returned. Pages are zero indexed, so the first page will be page 0 (zero). + **datafiles**: The datafiles key contains a list of file paths, which can be relative or complete URLs. These files contain additional information related to the returned object and can be retrieved by a subsequent call. The empty list should be returned if no additional data files are present. + **status**: The status object contains a list of objects with the keys "code" and "message". If no status is reported, an empty list should be returned. The following are officially accepted status codes: Code|Message|Description --|--|-- asynchid||Used for the first part of an asynchornous call, returns an ID string which can be used in a subsequent call to retrieve data or status information. asynchstatus|"PENDING"|Indicates an asynchornous call is still working and will not return data yet. asynchstatus|"FINISHED"|Indicates an asynchornous call is finished and this response object contains the requested data. 200|"Success"|Optional status for representing explicitly that the request was accepted and returned without any issue 40|"No objects found for given parameters"| Error to be returned when there are no objects in the database which match the requested search parameters 41|"Missing required parameter "| Error to be returned when a required parameter is missing from request 42|"Could not update values for "| Error to be returned when the server is unable to store some data submitted #### Payload The BRAPI response payload, which is contained in the "result" key, allows for three different types of responses: + **master**: In this type of response, the "result" key consists of arbitrary properties without a "data" key (in this case, pagination does not apply). ```` { "metadata" : { "pagination" : { "totalCount" : 0, "pageSize" : 0, "totalPages" : 0, "currentPage" : 0 }, "status" : [ ], "datafiles" : [ ] }, "result" : { "key0": "master", "key1": 20, "key2": [ "foo", "bar", "baz" ] } } ```` + **detail**: In this type of response, the "result" element only contains the "data" key, which is an arbitrarily long array of objects of the same type. ```` { "metadata" : { "pagination" : { "totalCount" : 20, "pageSize" : 3, "totalPages" : 7, "currentPage" : 0 }, "status" : [ ], "datafiles" : [ ] }, "result" : { "data" : [ { "detailKey0" : "detail0", "detailKey1" : [ "foo", "bar" ] }, { "detailKey0" : "detail1", "detailKey1" : [ "bar", "baz" ] }, { "detailKey0" : "detail2", "detailKey1" : [ "baz", "foo" ] }, ] } } ```` + **master/detail**: In this type of response, the "result" key contains both arbtirary properties and the "data" key. ```` { "metadata" : { "pagination" : { "totalCount" : 20, "pageSize" : 3, "totalPages" : 7, "currentPage" : 0 }, "status" : [ ], "datafiles" : [ ] }, "result" : { "key0": "master", "key1": 20, "key2": [ "foo", "bar", "baz" ], "data" : [ { "detailKey0" : "detail0", "detailKey1" : [ "foo", "bar" ] }, { "detailKey0" : "detail1", "detailKey1" : [ "bar", "baz" ] }, { "detailKey0" : "detail2", "detailKey1" : [ "baz", "foo" ] }, ] } } ```` Additional documentation is in the [GitHub wiki](https://github.com/plantbreeding/documentation/wiki). See especially the [Best Practices and Conventions] (https://github.com/plantbreeding/documentation/wiki/Best-Practices-and-Conventions). ### HTTP error codes HTTP error codes are used as required, e.g., 200 for ok, 404 for page not found, 401 for not authorized, 501 for not implemented, 201 for created in a PUT, 202 for request received but not yet processed, etc. All capturable errors should be responded to with the appropriate HTTP error code and a well forumlated JSON structure that includes a message describing the error. The error code is intedended as a debugging tool for the service provider. An example: + Response 400 (application/json) { "metadata" : { "pagination": { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [ { "message": "Unable to parse POST request", "code" : "" } ], "datafiles": [] }, "result": {} } ### Date and timestamp fields Date and timestamp fields are coded in the ISO 8601 standard, extended format. If the field name ends in "Date", only the date portion should be provided, for example "2017-06-16". If a field ends in "Timestamp", the date, time and time zone information needs to be provided, as in this example: "2017-06-16T14:47:23-0600". In version 1, milliseconds are not supported. --|Format|Example --|--|-- Date|yyyy-MM-dd|2017-06-16 Timestamp|yyyy-MM-ddThh:mm:ssz|2017-06-16T14:47:23-0600 Timestamp UTC|yyyy-MM-ddThh:mm:ssZ|2017-06-16T20:47:23Z ### Location coordinate encoding To encode locations as coordinates, the ISO 6709 standard is used. Importantly, the decimal notation is used. Example latitude: +40.20361, longitude: -075.00417. Note that plus and minus signs are always required, and latitude has two digits before the decimal separator (with leading zeroes when necessary), and longitude has three digits. ### Asynchronous Processing Some calls initiate asynchronous processing, which take an indeterminate amount of time to complete. For example, the allelematrix-search may initiate a background process that extracts the requested data from a data warehouse. In this case, + The status array of the call's response will contain a status object in which the value of the **code** key is **asynchid**, the value of the **message** key is an id that will be used in additional calls; + The resource from which the response was received will have a child resource called **status** to which the message value of the **asynchid** code is a uri parameter; a GET on this resource will indicate the current status of the job; + The status array of the response from the status resource will include a status object in which the key is called **asynchstatus** and the **message** key's value indicatse the following possible states with the specified meanings: + PENDING: The background process has not started to work on the job; + INPROCESS: The background process is working on the job; + FINISHED: The job has completed succesfully, in which case: + The datafiles list of the response with this **asynchstatus** message value is required to have at least one entry that is a file path or uri to the directory or file of interest; and/or + The data array in the result contains the matrix data; + FAILED: The job has failed; + In the case where the message value of the **asynchstatus** code is FAILED, the status array may have, but is not requried to have, a status object in which the **code** key is **asynchfailure** and the **message** key indicates the cause of the job failure (some systems may prefer to use email notification either instead of or in addition to this mechanism). For example, a call to allelematrix-search might give the following response: { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [{"code": "asynchid", "message" : "extract_2016-12-15-20-37-015"}], "datafiles": [] }, "result" : { "data": [] } } Given this response, a GET on the resource **/allelematrix-search/status/extract_2016-12-15-20-37-015** will give a response as follows: { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [{"code" : "asycnstatus" , "message" : "FINISHED"}], "datafiles": ["/shared_files/app_test/file_bundle/crops/rice/extract/output/721"] }, "result" : { "data": [] } } ### Search Services There are several "Search" calls specified in BrAPI. These calls have a postfix of "-search" in the name, and are used to search for a set of entities without knowing the primary key (DbId). These calls can be used when presenting search options to a user, or when a system needs to access an entity using a candidate key which is not the DbId. All search calls should have a set of optional parameters, which are specific to that entity and its fields. Each optional parameter included in any search service call should act as a filter on the data being returned. This means the search parameters should always have an 'AND' type relationship with each other. For example: Given this data ``` { id: "1", first: "Bob", last: "Jones" },{ id: "2", first: "Bob", last: "Smith" },{ id: "3", first: "Alice", last: "Jones" },{ id: "4", first: "Cathy", last: "Jones" } ``` The call `/person-search?first=Bob&last=Jones` will only return entity "1". The parameter `first` filters the data to just entities where the first name is "Bob" (entities "1" and "2"). The parameter `last` is an additional filter and further limits the data returned, resulting in just entity "1" satisfying both filters. When parameters are defined as lists, each item in the list acts as an accepted value for that parameter. This can be thought of as an 'OR' relationship for items within the same list parameter, or it could be considered a 'value IN array' type operation by a database. For example: Given the data above, the call `/person-search?first=Alice,Bob&last=Jones` will return entities "1" and "3". In this case, the parameter `first` filters the data to the first 3 entities, including all entities where the first name is 'Alice' OR 'Bob'. Again, the parameter `last` is an additional filter, further limiting the data returned, resulting in just entities "1" and "3" satisfying both filters. These rules for search parameters apply to both GET call query parameters and POST call body parameters. ### API call categories: Scope: "CORE", "PHENOTYPING", "GENOTYPING", "OTHER". Status: "STABLE", "ACCEPTED", "IN DISCUSSION", "SUGGESTED". # Group Authentication This resource refers to the authentication mechanism for the API. It is still implementation-agnostic but the structure should be similar across all implementations. To start off, we propose to use a call similar to OAuth2.0 password grant type. However, this is not fully secure, as we have to trust third party applications not to do anything nefarious with the password information. Upgrade to full OAuth2.0 in the future. To log in, we use a POST call and to log out we use a DELETE call. In order to remain as compliant as possible with OAuth2 ( https://tools.ietf.org/html/rfc6749 , 7.1. Access Token Types) the access token should be provided by the client in its HTTP header using the format "Authorization: Bearer {bearer_value}". When authenticated, all the calls, including the authentication call, should be done through HTTPS in order to keep the token safe. The token life time is fixed. If additional time is required, a new /token call should be made to obtain a new access token. **HTTPS** should be enforced everywhere. ## Authentication [/brapi/v1/token] Implemented by: Tripal Brapi module, Cassavabase, Germinate Used by: Flapjack ###### Response data types Exception: the result is not embeded in a "result" structure in order to be (one day) OAuth2 compliant. It's also why the anwser mixes snake_case and camelCase. For login, returns a hash with the user name and the token as the value. A metadata key is also present (but usually set to null, unless an error condition occurs). For logout, returns an empty resource. A token to remove could be provided (amdin interface) but it is not required. By default, current user token will be removed. |Variable|Datatype|Description|Required| |------|------|------|:-----:| | userDisplayName| string| the display name of the user | Y | | access_token | string | the access token for the session | Y | | expires_in | integer | The lifetime in seconds of the access token | Y | ### Login [POST] + Request (application/json) { "grant_type" : "password", //(optional, text, `password`) ... The grant type, only allowed value is password, but can be ignored "username" : "user38", // (required, text, `thepoweruser`) ... The username "password" : "secretpw", // (optional, text, `mylittlesecret`) ... The password "client_id" : "blabla" // (optional, text, `blabla`) ... The client id, currently ignored. } + Response 201 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [], "datafiles": [] }, "userDisplayName": "John Smith", "access_token": "R6gKDBRxM4HLj6eGi4u5HkQjYoIBTPfvtZzUD8TUzg4", "expires_in": "The lifetime in seconds of the access token" } ### Logout [DELETE] + Request (application/json) { "access_token" : "R6gKDBRxM4HLj6eGi4u5HkQjYoIBTPfvtZzUD8TUzg4" // (optional, text, `R6gKDBRxM4HLj6eGi4u5HkQjYoIBTPfvtZzUD8TUzg4`) ... The user access token. Default: current user token. } + Response 201 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [ { "message" : "User has been logged out successfully."} ], "datafiles": [] } "result" : {} } # Group Calls ## Call Search [/brapi/v1/calls] Status: ACCEPTED Implemented by: Germinate, Cassavabase Used by: Flapjack ##### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |datafiles|list|List of the data files generated by the call|Y| |data|array of objects|Array (possibly empty) of call records|Y| |call|string|The relative URL/path of the call as specified in the Apiary (e.g. "germplasm/{germplasmDbId}")|Y| |datatypes|list|List of the data formats supported for data export, e.g. "json", "tsv", etc.|Y| |methods|list|List of the HTTP methods supported by this call|Y| **Note on the call response** Having a consistent structure for the path string of each call is very important for teams to be able to connect and find errors. Read more on [Github](https://github.com/plantbreeding/API/issues/144). Here are the rules for the path of each call that should be returned: - Every word in the call path should match the documentation exactly, both in spelling and capitalization. Note that path strings are all lower case, but path parameters are camel case. - Each path should start relative to '/brapi/v1/' and therefore should not include '/brapi/v1/' - No leading or trailing slashes ('/') - Path parameters are wrapped in curly braces ('{}'). The name of the path parameter should be spelled exactly as it is specified in the documentation. |Examples|| |--|--| | **GOOD** |"call": "germplasm/{germplasmDbId}/markerprofiles" | | BAD |"call": "germplasm/{**id**}/markerprofiles" | | BAD |"call": "germplasm/{germplasmDbId}/marker**P**rofiles" | | BAD |"call": "germplasm/{germplasm**dbid**}/markerprofiles" | | BAD |"call": "**/brapi/v1**/germplasm/{germplasmDbId}/markerprofiles" | | BAD |"call": "**/g**ermplasm/{germplasmDbId}/markerprofiles **/"** | | BAD |"call": "germplasm/**\**/markerprofiles" | ### Call search [GET /brapi/v1/calls{?datatype}{?pageSize}{?page}] + 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, `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" : 8, "currentPage" : 0, "totalPages" : 1, "pageSize" : 1000 }, "datafiles" : [] }, "result" : { "data" : [ { "call": "token", "datatypes" : ["json"], "methods" : ["POST", "DELETE"] }, { "call": "calls" , "datatypes" : ["json"], "methods" : ["GET"] }, { "call": "allelematrix", "datatypes": ["json", "tsv"], "methods": ["GET", "POST"] }, { "call": "observationLevels", "datatypes" : ["json"], "methods" : ["GET"] }, { "call": "germplasm-search", "datatypes" : ["json"], "methods" : ["GET", "POST"] }, { "call": "germplasm/{germplasmDbId}", "datatypes" : [ "json" ], "methods" : ["GET"] }, { "call": "germplasm/{germplasmDbId}/pedigree", "datatypes" : ["json"], "methods" : ["GET"] }, { "call": "germplasm/{germplasmDbId}/markerprofiles", "datatypes" : [ "json" ], "methods" : ["GET"]} ] } } # Group Germplasm Fun Fact: The plural of germplasm is germplasm (no "s"). ## Germplasm Search [/brapi/v1/germplasm-search] Implemented by: GnpIS, Germinate (GET only) See Search Services for additional implementation details. Notes: The germplasm and gerplasm MCPD calls were merged. The MCPD fields are optional and indicated as such with the [MCPD] prefix in the description field of the 'Response data types' table. Please use the 'features' hash of the 'calls' call to communicate with clients as to whether MCPD is supported by your implementation. Adresses these needs: 1. General germplasm search mechanism that accepts POST for complex queries 2. possibility to search germplams by more parameters than those alowed by the existing germplasm search 3. possibility to get MCPD details by PUID rather than dbId ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|data|Y| |data|array of objects|Array (possibly empty) of germplasm records|Y| |germplasmDbId|string|Internal database identifier|Y| |defaultDisplayName|string|A string that can be displayed to the user|Y| |accessionNumber|string|This is the unique identifier for accessions within a genebank, and is assigned when a sample is entered into the genebank collection|| |germplasmName|string|Name of the germplasm. It can be the prefered name and does not have to be unique|| |germplasmPUI|string|Permanent identifier (e.g. URI, DOI, LSID)|| |pedigree|string|Cross name with optional selection history.|| |seedSource|string|Seed source|| |synonyms|array of string|List of other germplasm name|| |commonCropName|string|[MCPD] Common name fo the crop (e.g. wheat, rice, maize, cassava, banana)|| |instituteCode|string|[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| |instituteName|string|[MCPD] Name of the institute (or person) that bred the material.|| |biologicalStatusOfAccessionCode|string|[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|| |countryOfOriginCode|string|[MCPD] 3-letter ISO 3166-1 code of the country in which the sample was originally collected (e.g. landrace, crop wild relative, farmers' variety), bred or selected (breeding lines, GMOs, segregating populations, hybrids, modern cultivars, etc.).|| |typeOfGermplasmStorageCode|array of string|[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)|| |genus|string|[MCPD] Genus name for taxon. Initial uppercase letter required.|| |species|string|[MCPD] Specific epithet portion of the scientific name in lowercase letters.|| |taxonIds|array| The list of IDs for this SPECIES from different sources. If present, NCBI Taxon should be always listed as "ncbiTaxon" preferably with a purl. The rank of this ID should be species.|| |speciesAuthority|string|[MCDP]|| |subtaxa|string|[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’).| |subtaxaAuthority|string|[MCDP] || |donors|array of object|[MCPD] code of the donor institute and Identifier assigned to an accession by the donor, and permanent identifier.|| |acquisitionDate|string|[MCPD] Follow ISO 8601 standard| ### Germplasm search through GET [GET /brapi/v1/germplasm-search{?germplasmPUI}{?germplasmDbId}{?germplasmName}{?pageSize}{?page}] Use GET when parameter size is less than 2K bytes. + Parameters + germplasmPUI (optional, string, `http://data.inra.fr/accession/234Col342`) ... Permanent unique identifier (DOI, URI, etc.) + germplasmDbId (optional, string, `986`) ... Internal database identifier + germplasmName (optional, string, `Pahang`) ... Name of the germplasm + 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": { "status": [], "datafiles": [], "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 } }, "result": { "data": [ { "germplasmDbId": "01BEL084609", "defaultDisplayName": "Pahang", "accessionNumber": "ITC0609", "germplasmName": "Pahang", "germplasmPUI": "http://www.crop-diversity.org/mgis/accession/01BEL084609", "pedigree": "TOBA97/SW90.1057", "germplasmSeedSource": "Female GID:4/Male GID:4", "synonyms": [ ], "commonCropName": "banana", "instituteCode": "01BEL084", "instituteName": "ITC", "biologicalStatusOfAccessionCode": 412, "countryOfOriginCode": "UNK", "typeOfGermplasmStorageCode": [10], "genus": "Musa", "species": "acuminata", "taxonIds": [ { "sourceName":"ncbiTaxon", "taxonId":"http://purl.obolibrary.org/obo/NCBITaxon_4641" }, { "sourceName":"ciradTaxon", "taxonId":"23-E"}], "speciesAuthority": "", "subtaxa": "sp malaccensis var pahang", "subtaxaAuthority": "", "donors": [ { "donorAccessionNumber": "", "donorInstituteCode": "", "germplasmPUI": "" } ], "acquisitionDate": "1947-01-31" }, { "germplasmDbId": "03REL084609", "defaultDisplayName": "Pah", "accessionNumber": "ITC0685", "germplasmName": "Pah", "germplasmPUI": "doi:10.15454/328757862534E12", "pedigree": "TOBA97/SW90.1057", "germplasmSeedSource": "Female GID:4/Male GID:4", "synonyms": [ ], "commonCropName": "banana", "instituteCode": "01BEL084", "instituteName": "ITC", "biologicalStatusOfAccessionCode": 412, "countryOfOriginCode": "UNK", "typeOfGermplasmStorageCode": [10], "genus": "Musa", "species": "acuminata", "taxonIds": [ { "sourceName":"ncbiTaxon", "taxonId":"http://purl.obolibrary.org/obo/NCBITaxon_4641" }, { "sourceName":"ciradTaxon", "taxonId":"23-E"}], "speciesAuthority": "", "subtaxa": "sp malaccensis var pah", "subtaxaAuthority": "", "donors": [ { "donorAccessionNumber": "", "donorInstituteCode": "", "germplasmPUI": "" } ], "acquisitionDate": "1977-01-31" } ] } } ### Germplasm search through POST [POST /brapi/v1/germplasm-search] Use POST for large queries (>2K bytes). + Request (application/json) { "germplasmPUIs" : [ "http://www.crop-diversity.org/mgis/accession/01BEL084609", "doi:10.15454/328757862534E12" ], "germplasmDbIds" : [ "986", "01BEL084609" ], "germplasmSpecies" : [ "aestivum", "vinifera" ], "germplasmGenus" : [ "Solanum", "Triticum" ], "germplasmNames" : [ "XYZ1", "Pahang" ], "accessionNumbers": [ "ITC0609", "ITC0685" ], "pageSize" : 100, "page": 1 } + Response 200 (application/json) { "metadata": { "status": [], "datafiles": [], "pagination": { "pageSize": 100, "currentPage": 1, "totalCount": 102, "totalPages": 2 } }, "result": { "data": [ { "germplasmDbId": "01BEL084609", "defaultDisplayName": "Pahang", "accessionNumber": "ITC0609", "germplasmName": "Pahang", "germplasmPUI": "http://www.crop-diversity.org/mgis/accession/01BEL084609", "pedigree": "TOBA97/SW90.1057", "germplasmSeedSource": "Female GID:4/Male GID:4", "synonyms": [ ], "commonCropName": "banana", "instituteCode": "01BEL084", "instituteName": "ITC", "biologicalStatusOfAccessionCode": 412, "countryOfOriginCode": "UNK", "typeOfGermplasmStorageCode": [10], "genus": "Musa", "species": "acuminata", "taxonIds": [ { "sourceName":"ncbiTaxon", "taxonId":"http://purl.obolibrary.org/obo/NCBITaxon_4641" }, { "sourceName":"ciradTaxon", "taxonId":"23-E"}], "speciesAuthority": "", "subtaxa": "sp malaccensis var pahang", "subtaxaAuthority": "", "donors": [ { "donorAccessionNumber": "", "donorInstituteCode": "", "germplasmPUI": "" } ], "acquisitionDate": "1947-01-31" }, { "germplasmDbId": "03REL084609", "defaultDisplayName": "Pah", "accessionNumber": "ITC0685", "germplasmName": "Pah", "germplasmPUI": "doi:10.15454/328757862534E12", "pedigree": "TOBA97/SW90.1057", "germplasmSeedSource": "Female GID:4/Male GID:4", "synonyms": [ ], "commonCropName": "banana", "instituteCode": "01BEL084", "instituteName": "ITC", "biologicalStatusOfAccessionCode": 412, "countryOfOriginCode": "UNK", "typeOfGermplasmStorageCode": [10], "genus": "Musa", "species": "acuminata", "taxonIds": [ { "sourceName":"ncbiTaxon", "taxonId":"http://purl.obolibrary.org/obo/NCBITaxon_4641" }, { "sourceName":"ciradTaxon", "taxonId":"23-E"}], "speciesAuthority": "", "subtaxa": "sp malaccensis var pah", "subtaxaAuthority": "", "donors": [ { "donorAccessionNumber": "", "donorInstituteCode": "", "germplasmPUI": "" } ], "acquisitionDate": "1977-01-31" } ] } } ## Germplasm Details by germplasmDbId [/brapi/v1/germplasm/{germplasmDbId}] Scope: CORE. Status: ACCEPTED. Implementation target date: PAG2016 Implemented by: Tripal Brapi module, Germinate, Cassavabase Note: Germplasm Details by germplasmDbId was merged with Germplasm Multi Crop Passport Data. The MCPD fields are optional and marked with the prefix [MCPD]. ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|Object containing MCPD data|Y| |germplasmDbId|string|Internal db identifier|Y| |defaultDisplayName|string|A string that can be displayed to the user|Y| |accessionNumber|string|This is the unique identifier for accessions within a genebank, and is assigned when a sample is entered into the genebank collection|| |germplasmName|string|Name of the germplasm. It can be the prefered name and does not have to be unique|| |germplasmPUI|string|Permanent identifier (e.g. URI, DOI, LSID)|| |pedigree|string|Cross name with optional selection history.|| |seedSource|string|Identifier of the original lot.|| |synonyms|array of string|List of other germplasm name|| |commonCropName|string|Common name for the crop (e.g. wheat, rice, maize, cassava, banana)|| |instituteCode|string|[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| |instituteName|string|[MCPD] Name of the institute (or person) that bred the material.|| |biologicalStatusOfAccessionCode|string|[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|| |countryOfOriginCode|string|[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.).|| |typeOfGermplasmStorageCode|array of string|[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)|| |genus|string|[MCPD] Genus name for taxon. Initial uppercase letter required.|| |species|string|[MCPD] Specific epithet portion of the scientific name in lowercase letters.|| |taxonIds|array| The list of IDs for this SPECIES from different sources. If present, NCBI Taxon should be always listed as "ncbiTaxon" preferably with a purl. The rank of this ID should be species.|| |speciesAuthority|string|[MCPD]|| |subtaxa|string|[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’).| |subtaxaAuthority|string|[MCPD] || |donors|array of object|[MCPD] code of the donor institute and Identifier assigned to an accession by the donor, and permanent identifier.|| |acquisitionDate|string|[MCPD] Follow ISO 8601 standard| ### Germplasm search by germplasmDbId [GET /brapi/v1/germplasm/{germplasmDbId}] + Parameters + germplasmDbId (required, string, `382`) ... The internal id of the germplasm + Response 200 (application/json) { "metadata": { "status": [], "datafiles": [], "pagination": { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 } }, "result": { "germplasmDbId": "01BEL084609", "defaultDisplayName": "Pahang", "accessionNumber": "ITC0609", "germplasmName": "Pahang", "germplasmPUI": "http://www.crop-diversity.org/mgis/accession/01BEL084609", "pedigree": "TOBA97/SW90.1057", "seedSource": "ITC0609-2016-77", "synonyms": [ ], "commonCropName": "banana", "instituteCode": "01BEL084", "instituteName": "ITC", "biologicalStatusOfAccessionCode": 412, "countryOfOriginCode": "UNK", "typeOfGermplasmStorageCode": [10], "genus": "Musa", "species": "acuminata", "taxonIds": [ { "sourceName":"ncbiTaxon", "taxonId":"http://purl.obolibrary.org/obo/NCBITaxon_4641" }, { "sourceName":"ciradTaxon", "taxonId":"23-E"}], "speciesAuthority": "", "subtaxa": "sp malaccensis var pahang", "subtaxaAuthority": "", "donors": [ { "donorAccessionNumber": "", "donorInstituteCode": "", "donorGermplasmPUI": "" } ], "acquisitionDate": "1947-01-31" } } ## Germplasm Pedigree [/brapi/v1/germplasm/{germplasmDbId}/pedigree] Scope: CORE. Status: ACCEPTED. Implementation target date: PAG2016 Implemented by: Germinate, Tripal Brapi Module, Cassavabase (without notation option) ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |germplasmDbId|string|Internal db identifier|Y| |defaultDisplayName|string|A string representing the germplasm that will be meaningful to the user|Y| |pedigree|string|Cross name with optional selection history.|Y| |**Deprecated** parent1Id|string|**Use parent1DbId**|| |**Deprecated** parent2Id|string|**Use parent2DbId**|| |parent1DbId|string|germplasmDbId of parent1|| |parent2DbId|string|germplasmDbId of parent2|| (http://wheat.pw.usda.gov/ggpages/gopher/administration/Template%20for%20Germplasm%20records.html) or [Lamacraft] (http://link.springer.com/article/10.1007%2FBF00021556). ### Germplasm pedigree by id [GET /brapi/v1/germplasm/{germplasmDbId}/pedigree{?notation}] + Parameters + germplasmDbId (required, string, `382`) ... the internal id of the germplasm + notation (optional, string, `purdy`) ... text representation of the pedigree + Response 200 (application/json) { "metadata" : { "pagination": { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status": [], "datafiles": [] } "result" : { "germplasmDbId": "382", "defaultDisplayName": "Pahang", "pedigree" : "Cree / Bonanza", "parent1DbId" : "166", "parent2DbId" : "143" } } ## Germplasm Markerprofiles [/brapi/v1/germplasm/{germplasmDbId}/markerprofiles] Retrieve the markerProfileDbIds for a given Germplasm ID Scope: GENOTYPING. Status: ACCEPTED. Implementation target date: PAG2016 Implemented by: Germinate, Cassavabase ### Markerprofiles by germplasmDbId [GET /brapi/v1/germplasm/{germplasmDbId}/markerprofiles] + Parameters + germplasmDbId (required, string, `382`) ... the internal id of the germplasm + Response 200 (application/json) { "metadata" : { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [ { "message": "", "code" : "" } ], "datafiles": [] }, "result" : { germplasmDbId : "39393", markerprofileDbIds : [ "3939", "4484", "3993" ] } } # Group Germplasm Attributes Germplasm "attributes" are simply-inherited characteristics (characterization descriptors) that are not environment-dependent but inherent in the germplasm line. They include genes, QTLs, and genetic "traits" like wheat grain hardness. They are often evaluated by genotyping for diagnostic markers. ## List attributes available [/brapi/v1/attributes] Scope: OTHER. Status: ACCEPTED. Implementation target date: PAG2016 ### Attributes by attributeCategoryDbId [GET /brapi/v1/attributes{?attributeCategoryDbId}{?pageSize}{?page}] List available attributes. ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |attributeCategoryDbId|string|internal database identifier, not stable |Y| |code|string|abbreviation|| |uri|string|reference to external documentation, ontology etc.|| |name|string|for display, and stable identifier unique in the database|Y| |description|string||| |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 + 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": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "attributeCategoryDbId": "1", "code": "RHT", "uri": "http://www.cropontology.org/rdf/CO_321:0000020", "name": "Rht-B1b", "description": "Allele of marker 11_4769, diagnostic for allele b of reduced-height gene Rht-B1", "datatype": "Categorical", "values": ["Present", "Absent", "Heterozygous"] } ] } } ## List attribute categories [/brapi/v1/attributes/categories] Scope: OTHER. Status: ACCEPTED. Implementation target date: PAG2016 ### Germplasm attribute categories [GET /brapi/v1/attributes/categories{?pageSize}{?page}] List all available attribute categories. + 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": 10, "currentPage": 1, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "attributeCategoryDbId": "1", "name": "Morphological" }, { "attributeCategoryDbId": "2", "name": "Agronomic" } ] ] } ## Germplasm attribute values by germplasmDbId [/brapi/v1/germplasm/{germplasmDbId}/attributes] Status: ACCEPTED.] ### Germplasm attribute values [GET /brapi/v1/germplasm/{germplasmDbId}/attributes{?attributeList}{?pageSize}{?page}] Values for all attributes by default. + Parameters + germplasmDbId (required, string, `993`) ... The germplasm characterized + attributeList (optional, array, `123,456,789`) ... Restrict the response to only the listed attributeDbIds. + 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": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : [ { "germplasmDbId": "993", "data": [ { "attributeDbId": "1", "attributeName": "Rht-B1b", "attributeCode": "RHT", "value": "Present", "determinedDate": "2007-05-28" } ] } ] } # Group Markers ## Markers Search [/brapi/v1/markers-search] Scope: CORE. Status: ACCEPTED. Implemented by: Germinate See Search Services for additional implementation details. Other service requests use the server's internal `markerDbId`. This service returns marker records that provide the markerDbId. For the requested name or synonym, returns an array (possibly empty) of marker records that match the search criteria. - If there is none, an empty array is returned. - If there is one or more than one match, returns an array of all marker records that match the search criteria. ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|data|Y| |data|array of objects|Array (possibly empty) of marker records|Y| |type|string|The type of marker, e.g. SNP|Y| |markerDbId|string|Internal db identifier|Y| |defaultDisplayName|string|A string representing the marker that will be meaningful to the user|Y| |synonyms|array of string|List of other names for this marker|| |refAlt|array of string|List of the reference (as the first item) and alternatives (the remaining items)|| |analysisMethods|array of string|List of the genotyping platforms used to interrogate the marker|| ### **Deprecated** Markers Search (/brapi/v1/markers) [GET /brapi/v1/markers?name={name}&type={type}&matchMethod={matchMethod}&include={include}&pageSize={pageSize}&page={page}] + Parameters + name (optional, string, `11_10002 11_1% 11_1* 11_10?02`) ... The name or synonym. + matchMethod (optional, string, `wildcard`) ... Possible values are 'case_insensitive', 'exact' (case sensitive), 'wildcard' (which is case insensitive). Wildcard uses both '*' and '%' for any number of characters and '?' for one character matching. Default is exact. + include (optional, string, `synonyms`) ... Whether to include synonyms in the output. + type (optional, string, `SNP`) ... The type of the marker. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data": [ { "markerDbId": "1185", "defaultDisplayName": "11_10002", "type": "SNP", "synonyms": ["i_11_10002", "POPA1_0002"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] }, { "markerDbId": "1186", "defaultDisplayName": "11_11159", "type": "SNP", "synonyms": ["i_11_11159", "POPA1_1159"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] } ] } } ### Markers Search (GET) [GET /brapi/v1/markers-search{?markerDbIds}{?name}{?matchMethod}{?includeSynonyms}{?type}{?pageSize}{?page}] + Parameters + markerDbIds (optional, array, `1185,1186`) ... The database IDs of the markers to search for + name (optional, string, `11_1*`) ... The search pattern for a marker name or synonym. Examples: "11_10002" "11_1%" "11_1*" "11_10?02" + matchMethod (optional, string, `wildcard`) ... Possible values are 'case_insensitive', 'exact' (case sensitive), 'wildcard' (which is case insensitive). Wildcard uses both '*' and '%' for any number of characters and '?' for one character matching. Default is exact. + includeSynonyms (optional, boolean, `true`) ... Whether to include synonyms in the output. + type (optional, string, `SNP`) ... The type of the marker. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data": [ { "markerDbId": "1185", "defaultDisplayName": "11_10002", "type": "SNP", "synonyms": ["i_11_10002", "POPA1_0002"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] }, { "markerDbId": "1186", "defaultDisplayName": "11_11159", "type": "SNP", "synonyms": ["i_11_11159", "POPA1_1159"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] } ] } } ### Markers Search (POST) [POST /brapi/v1/markers-search] + Request + Body { "markerDbIds": ["1185", "1186"], // The database IDs of the markers to search for "name": "11_1*", // The search pattern for a marker name or synonym. "matchMethod": "wildcard", // Possible values are 'case_insensitive', 'exact' (case sensitive), 'wildcard' (case insensitive). Wildcard uses both '*' and '%' for any number of characters and '?' for one character matching. Default is exact. "includeSynonyms": true, // Whether to include synonyms in the output. "type": "SNP", // The type of the marker. "pageSize": 1000, // The size of the pages to be returned. Default is `1000`. "page": 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data": [ { "markerDbId": "1185", "defaultDisplayName": "11_10002", "type": "SNP", "synonyms": ["i_11_10002", "POPA1_0002"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] }, { "markerDbId": "1186", "defaultDisplayName": "11_11159", "type": "SNP", "synonyms": ["i_11_11159", "POPA1_1159"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] } ] } } ## Marker Details by markerDbId [/brapi/v1/markers/{markerDbId}] Status: ACCEPTED Implemented By: ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status, datafiles|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|marker data|Y| |type|string|The type of marker, e.g. SNP|Y| |markerDbId|string|Internal db identifier|Y| |defaultDisplayName|string|A string representing the marker that will be meaningful to the user|Y| |synonyms|array of string|List of other names for this marker|| |refAlt|array of string|List of the reference (as the first item) and alternatives (the remaining items)|| |analysisMethods|array of string|List of the genotyping platforms used to interrogate the marker|| ### Marker Details by id [GET /brapi/v1/markers/{markerDbId}] + Parameters + markerDbId (required, string, `1185`) ... the internal id of the marker + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [], }, "result": { "markerDbId": "1185", "defaultDisplayName": "11_10002", "type": "SNP", "synonyms": ["i_11_10002", "POPA1_0002"], "refAlt": ["A", "T"], "analysisMethods": ["illumina", "kasp"] } } # Group Markerprofiles For the purposes of this API, the definition of markerprofile is *the allele calls for a specified germplasm line, for all markers, for a specified set of genotyping experiments or all experiments.* Basic concepts in the **Breeding API**: - *markerprofile*: A set of marker scores for a specific extract from a specific germplasm. - *extract* : a preparation from a germplasm for an analysis. - *sample*: an individual plant or tissue from a plant of a particular germplasm - *germplasm*: a single genetic entity (cultivar, variety, accession, breeding line) used for analysis - *marker*: a DNA sequence polymorphism, potentially localized to a single genomic location - *allele*: one of the two possible states of a marker in each haploid chromosome complement of a specified germplasm, as determined in a specified experiment. A diploid organism has two alleles per marker. - *missing*: a germplasm/marker/experiment combination for which no allele result is available, whether it was tested for or not ## Markerprofile search [/brapi/v1/markerprofiles] Scope: GENOTYPING. Status: ACCEPTED. Implemented by: Germinate Used by: Flapjack For the requested Germplasm Id and/or Extract Id, returns the Markerprofile Id and number of non-missing allele calls (marker/allele pairs). ### Retrieve Markerprofile Ids [GET /brapi/v1/markerprofiles{?germplasmDbId}{?studyDbId}{?sampleDbId}{?extractDbId}{?methodDbId}{?pageSize}{?page}] + Parameters + germplasmDbId (optional, string, `993`) ... The server's internal ids for the Germplasm IDs, as returned by the **Find markerprofile by Germplasm** service. + studyDbId (optional, string, `111`) ... The server's internal id for the StudyDbId + 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 page indexing starts at 0 (the first page is 'page'=0) + Response 200 (application/json) { "metadata" : { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "markerprofileDbId": "993", "germplasmDbId" : "2374", "uniqueDisplayName": "MyFancyGermplasm", "sampleDbId" : "3937", "extractDbId" : "3939", "analysisMethod": "GoldenGate", "resultCount": 1470 }, { "markerprofileDbId": "994", "germplasmDbId" : "2374", "uniqueDisplayName" : "Germplasm2", "sampleDbId" : "1234", "extractDbId" : "3939", "analysisMethod": "GBS", "resultCount": 1470 } ] } } ## Markerprofile data [/brapi/v1/markerprofiles/{markerprofileDbId}] Scope: GENOTYPING. Status: ACCEPTED. Implemented by: Germinate, Cassavabase For the requested markerprofile ID, returns the allele call for each marker. [Example] (http://malt.pw.usda.gov/t3/wheatplus/brapi/v1/markerprofiles/1784_99/count?analysisMethod=GoldenGate) **Allele encodings** - Unknown data will by default be encoded by "N" - Homozygotes are returned as a single occurance, e.g. AA -> A, GG -> G - Phased heterozygotes are by default separated by a pipe ("|") and unphased heterozygotes are by default separated by a forward slash ("/") - Dominant markers such as DArTs: 1 for present, 0 for absent **Parameters** - If the user would like to use an empty string ("") for any of the parameters, the value should be set to the reserved word "empty_string", e.g. sepUnphased=empty_string. **Open issue:** The pages of data will need to be sorted sensibly in order for the requested page to be delivered consistently. By map or genome position? Alphabetically? ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |markerprofileDbId|string|Unique in the database. Can be a catenation of unique IDs for germplasm and extract.|Y| |germplasmDbId|string||Y| |extractDbId|string||Y| |analysisMethod|string||| |data|object|array of marker-name/score pairs|Y| |metadata|object|pagination, status, datafiles|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list||Y| ### Alleles By Markerprofile Id [GET /brapi/v1/markerprofiles/{markerprofileDbId}{?expandHomozygotes}{?unknownString}{?sepPhased}{?sepUnphased}{?pageSize}{?page}] + Parameters + markerprofileDbId (required, string, `993`) ... The server's internal id for the markerprofile + expandHomozygotes (optional, boolean, `false`) ... Should homozygotes NOT be collapsed into a single orrucance? + 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, `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 page indexing starts at 0 (the first page is 'page'=0) + Response 200 (application/json) { "metadata" : { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "germplasmDbId": "993", "uniqueDisplayName": "MyNameHere", "extractDbId" : "38383", "markerprofileDbId": "37484", "analysisMethod": "GBS-Pst1", "data" : [ { "marker1": "A" }, { "marker2":"A/B" }, ... ] } } ## MarkerProfile Allele Matrix [/brapi/v1/allelematrix-search] Status: ACCEPTED. Implemented by: Germinate (POST only), Cassavabase Used by: Flapjack (POST only) See Search Services for additional implementation details. This uses a more efficient data structure and pagination for large number of markers. |Variable|Datatype|Description|Required| |------|------|------|:-----:| |markerprofileDbIds| list of strings | | Y | |data| array | Is an array of arrays; each inner array has three entries: "markerDbId", "markerprofileDbId", "alleleCall". Scores have to be represented as described further up. e.g. unknown data as "N", etc. Missing data can be skipped. | Y | ### Scores through GET [GET /brapi/v1/allelematrix-search{?markerprofileDbId}{?markerDbId}{?matrixDbId}{?format}{?expandHomozygotes}{?unknownString}{?sepPhased}{?sepUnphased}{?pageSize}{?page}] Use GET when parameter size is less than 2K bytes. This method may support asynchronous processing. + Parameters + markerprofileDbId (required, array, `993,994,995`) ... The markerprofile db ids. Not Required if 'markerDbId' or 'matrixDbId' is present. + markerDbId (required, array, `322,323,324`) ... ids of the markers. if none are specified, results are returned for all markers in the database. Not Required if 'markerprofileDbId' or 'matrixDbId' is present. + matrixDbId (required, array, `457,458,459`) . . . ids of the complete matrix. Not Required if 'markerprofileDbId' or 'markerDbId' is present. + format (optional, string, `tsv`) ... format for the datafile to be downloaded. tsv and csv currently supported; flapjack may be supported. + expandHomozygotes (optional, boolean, `false`) ... Should homozygotes NOT be collapsed into a single occurrence? + 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 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": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data": [ ["1", "1", "A/B"], ["1", "2", "B"], ["2", "1", "A"], ["2", "2", "A/B"] ] } } ### Scores through POST [POST /brapi/v1/allelematrix-search] Use POST when parameter size is greater than 2K bytes. - If no format is specified, this call returns the data in JSON form. - If a format (other than JSON) is specified and the server supports this format, it will return the link to the exported data file in the "datafiles" field of the "metadata". - If more than one format is requested at a time, the server will throw a "501 Not Implemented" error. The format of the tsv response can be found on GitHub (https://github.com/plantbreeding/Documentation/wiki/BrAPI-TSV-Expected-Formats) + Request (application/json) { "markerprofileDbId": ["993","994","995], // (required) The markerprofile db ids. Not Required if 'markerDbId' or 'matrixDbId' is present. "markerDbId": ["322","323","324"], // (required) ids of the markers. if none are specified, results are returned for all markers in the database. Not Required if 'markerprofileDbId' or 'matrixDbId' is present. "matrixDbId": ["457","458","459"], // (required) ids of the complete matrix. Not Required if 'markerprofileDbId' or 'markerDbId' is present. "expandHomozygotes" : true, //(optional) Should homozygotes NOT be collapsed into a single orrucance? "unknownString" : "-", //(optional) The string to use as a representation for missing data. "sepPhased" : "|", //(optional) The string to use as a separator for phased allele calls. "sepUnphased" : "/", // (optional)The string to use as a separator for unphased allele calls. "format" : "tsv", // (optional) If specified, this indicates that the server should return the data in the specified data format. The link to the data file is then returned in the "datafiles" field of the "metadata". Initially only "tsv" is supported which returns the data in a tab-delimited format. MarkerprofileDbIds along the top, markerDbIds along the side and allele calls in the center. "pageSize" : 100, // (optional)the number of allele calls reported per response page. "page" : 1 // (optional) the requested response page } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 100, "currentPage": 1, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data": [ ["1", "1", "A/B"], ["1", "2", "B"], ["2", "1", "A"], ["2", "2", "A/B"] ] } } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [ "https://my-fancy-server/files/allelematrix-1234.tsv" ] }, "result" : { "data" : [] } } # Group Programs ## Program list [/brapi/v1/programs] Call to retrieve a list of programs. Status: ACCEPTED Implemented By: ### List programs [GET /brapi/v1/programs{?programName}{?abbreviation}{?pageSize}{?page}] + Parameters + programName (optional, string, `Internation Yield Trial`) ... Filter by program name. Exact match. + abbreviation (optional, string, `IYT`) ... Filter by program abbreviation. Exact match. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "programDbId": "123", "name": "Wheat Resistance Program", "abbreviation" : "DRP1", "objective" : "Disease resistance", "leadPerson" : "Dr. Henry Beachell" }, { "programDbId": "456", "name": "Wheat Improvement Program", "abbreviation" : "DRP2", "objective" : "Yield improvement", "leadPerson" : "Dr. Norman Borlaug" } ] } } ## Program Search [/brapi/v1/programs-search] Advanced searching for the programs resource. Status: ACCEPTED. See Search Services for additional implementation details. ### Search Programs [POST /brapi/v1/programs-search] + Request (application/json) { "programDbId": "123", "name": "Wheat Resistance Program", "abbreviation" : "DRP1", "objective" : "Disease resistance", "leadPerson" : "Dr. Henry Beachell", "pageSize": 1000, "page": 0 } + Response 200 (application/json) { "metadata" : { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "programDbId": "123", "name": "Wheat Resistance Program", "abbreviation" : "DRP1", "objective" : "Disease resistance", "leadPerson" : "Dr. Henry Beachell" }, { "programDbId": "456", "name": "Wheat Improvement Program", "abbreviation" : "DRP2", "objective" : "Yield improvement", "leadPerson" : "Dr. Norman Borlaug" } ] } } # Group Crops For multi crop systems this is a useful call to list all the supported crops. ## List supported crops [/brapi/v1/crops] Scope: CORE. Status: ACCEPTED. ### List supported crops [GET /brapi/v1/crops{?pageSize}{?page}] + 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": 1000, "currentPage": 0, "totalCount": 3, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data": [ "maize", "wheat", "rice" ] } } # Group Trials Services related to trials. Trials comprise of multiple studies. The trial concept in BrAPI corresponds to the "investigation" concept in MIAPPE (Minimal Information about a Plant Phenotyping Experiment). ## Get List of Trial Summaries [/brapi/v1/trials] Scope: PHENOTYPING. Status: ACCEPTED. Implementation target date: PAG2016. ###### Response data types | Variable | Datatype | Description | Required | | ----------------------- | --------------- | ------------------------------------------------------- | :------: | | trialDbId | string | string database identifier, not necessarily a Primary Key | Y | | trialName | string | Human readable name | Y | | programDbId | string | string database identifier, not necessarily a Primary Key | | | programName | string | | | | startDate | Date (ISO 8601) | | | | endDate | Date (ISO 8601) | | | | active | boolean | | | | studies | array of object | List of studies | | | studies.studyDbId | string | Study database identifier | | | studies.studyName | string | Study name | | | studies.locationName | string | Study location name | | | additionalInfo | object | Additional arbitrary info on the trial | | ### List of trial summaries [GET /brapi/v1/trials{?programDbId}{?locationDbId}{?pageSize}{?page}{?active}{?sortBy}{?sortOrder}] + Parameters + programDbId (optional, string, `1`) ... Program filter to only return trials associated with given program id. + locationDbId (optional, string, `212`) ... Filter by location + 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`. + active (optional, boolean, `true`) ... Filter active status true/false. + sortBy (optional, string, `studyDbId`) ... Sort order. Name of the field to sorty by. + sortOrder (optional, string, `asc`) ... Sort order direction: asc/desc + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data": [ { "trialDbId" : "1", "trialName" : "InternationalTrialA", "programDbId": "27", "programName": "International Yield Trial", "startDate": "2007-06-01", "endDate" : "2008-12-31", "active" : "false", "studies" : [ { "studyDbId" : "1", "studyName" : "Zimbabwe Yield Trial", "locationName" : "Zimbabwe" }, { "studyDbId" : "2", "studyName" : "Kenya Yield Trial", "locationName" : "Kenya" } ], "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } }, { "trialDbId" : "2", "trialName" : "InternationalTrialB", "programDbId": "35", "programName": "International Yield Trial 2: Return of the Trial", "startDate": "2008-06-01", "endDate" : "2009-12-31", "active" : "true", "studies" : [ { "studyDbId" : "3", "studyName" : "Zimbabwe Yield Trial", "locationName" : "Zimbabwe" }, { "studyDbId" : "4", "studyName" : "Kenya Yield Trial", "locationName" : "Kenya" } ], "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } } ] } } ## Get Trial By Id [/brapi/v1/trials/{trialDbId}] Scope: PHENOTYPING. Status: ACCEPTED. Implementation target date: PAG2016. Get trial by id. ###### Response data types | Variable | Datatype | Description | Required | | ----------------------- | --------------- | ------------------------------------------------------- | :------: | | trialDbId | string | string database identifier, not necessarily a Primary Key | Y | | trialName | string | Human readable name | Y | | programDbId | string | string database identifier, not necessarily a Primary Key | | | programName | string | | | | startDate | Date (ISO 8601) | | | | endDate | Date (ISO 8601) | | | | active | boolean | | | | datasetAuthorship | array of object | List of studies | | | datasetAuthorship.license | string | License for data use. If using a known license like CC-BY, use the URI (https://creativecommons.org/licenses/by/4.0/) | | | datasetAuthorship.datasetPUI | string | DOI or any other citation mechanism for this dataset | | | studies | array of object | List of studies | | | studies.studyDbId | string | Study database identifier | | | studies.studyName | string | Study name | | | studies.locationName | string | Study location name | | | studies.locationDbId | string | Study location db id | | | contacts | array of object | List of trial identifier | | | contacts.contactDbId | string | Study contact database identifier | | | contacts.name | string | Study contact name | | | contacts.instituteName | string | Study contact institute name | | | contacts.email | string | Study contact email | | | contacts.type | string | Study contact type (ex: Coordinator, Scientist, etc.) | | | contacts.orcid | string | Study contact orcid identifier (http://orcid.org) | | | additionalInfo | object | Additional arbitrary info on the trial like publications| | | additionalInfo.publications | array of string | Additional info for publications | | ### Get trial by Id [GET /brapi/v1/trials/{trialDbId}] + Parameters + trialDbId (required, string, `123abc`) ... The internal trialDbId + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [], "datafiles": [] }, "result": { "trialDbId" : 1, "trialName" : "InternationalTrialA", "programDbId": 27, "programName": "International Yield Trial", "startDate": "2007-06-01", "endDate" : "2008-12-31", "active" : "true", "datasetAuthorship":{ "license": "https://creativecommons.org/licenses/by/4.0", "datasetPUI":"doi:10.15454/312953986E3" }, "contacts": [ { "contactDbId": "C025", "name": "John Doe", "instituteName":"IRRI", "email": "j.doe@mail.com", "type": "Scientist", "orcid": "0000-0002-0607-8728" }, { "contactDbId": "C026", "name": "Dave Peters", "instituteName":"IRRI", "email": null, "type": null, "orcid": null } ], "studies" : [ { "studyDbId" : 1, "studyName" : "Zimbabwe Yield Trial", "locationName" : "Zimbabwe", "locationDbId" : "z-2" }, { "studyDbId" : 2, "studyName" : "Kenya Yield Trial", "locationName" : "Kenya", "locationDbId" : "k-1" } ], "additionalInfo" : { "publications" : ["pmid:239823988","doi:10.2345/GEZG3T23535"], "property2Name" : "property2Value", "property3Name" : "property3Value" } } } # Group Study Study is defined as a phenotyping experiment conducted at a single geographic location. One Trial can have multiple studies conducted (e.g. multi location international trials). Note that dates should be provided in extended ISO 8601 format (for example, "YYYY-MM-DD"). ## List Seasons [/brapi/v1/seasons] Call to retrive all seasons (or years) in the database. (Added by Jan-Erik and Lukas 5/26/2016) Scope: PHENOTYPING. ### List seasons or years [GET /brapi/v1/seasons{?year}{?pageSize}{?page}] + Parameters + year (optional, String, `2015`) + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "seasonDbId": "237", "season": "Fall", "year": "2015" }, { "seasonDbId": "238", "season": "Spring", "year": "2016" } ] } } ## List Study Types [/brapi/v1/studytypes] Call to retrieve the list of study types. Scope: PHENOTYPING. Implementation target date: PAG2016 ### **Deprecated** List study types [GET /brapi/v1/studyTypes?pageSize={pageSize}&page={page}] + 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": 1000, "currentPage": 0, "totalCount": 3, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "name": "Crossing Nursery", "description": "Description for Nursery study type" }, { "name": "Yield Trial", "description": "Description for Trial study type" }, { "name": "Genotype", "description": "Description for Genotyping study type" } ] } } ### List study types [GET /brapi/v1/studytypes{?pageSize}{?page}] + 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": 1000, "currentPage": 0, "totalCount": 3, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "name": "Crossing Nursery", "description": "Description for Nursery study type" }, { "name": "Yield Trial", "description": "Description for Trial study type" }, { "name": "Genotype", "description": "Description for Genotyping study type" } ] } } ## Search Studies [/brapi/v1/studies-search] Scope: PHENOTYPING. Status: ACCEPTED. Implementation target date: PAG2016. Implemented by: Germinate Used by: Flapjack, Cassavabase See Search Services for additional implementation details. Get list of studies StartDate and endDate should be ISO8601 format for dates: YYYY-MM-DD ### Search Studies (GET) [GET /brapi/v1/studies-search{?studyType}{?programDbId}{?locationDbId}{?seasonDbId}{?trialDbId}{?germplasmDbIds}{?observationVariableDbIds}{?pageSize}{?page}{?active}{?sortBy}{?sortOrder}] + Parameters + studyType (optional, string, `Nursery`) ... Filter based on study type e.g. Nursery, Trial or Genotype. + programDbId (optional, string, `1`) ... Program filter to only return studies associated with given program id. + locationDbId (optional, string, `212`) ... Filter by location + seasonDbId (optional, string, `2016E`) ... Filter by season or year + trialDbId (optional, string, `7`) ... Filter by trial + germplasmDbIds (optional, array, `CML123,CML`) ... Filter studies where specified germplasm have been used/tested + observationVariableDbIds (optional, array, `CO-PH-123,Var-123`) ... Filter studies where specified observation variables have been measured + 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`. + active (optional, boolean, `true`) ... Filter active status true/false. + sortBy (optional, string, `studyDbId`) ... Sort order. Name of the field to sort by. + sortOrder (optional, string, `asc`) ... Sort order direction. Ascending/Descending. + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data": [ { "studyDbId": "35", "name": "Earlygenerationtesting", "trialDbId" : "7", "trialName" : "InternationalTrialA", "studyType": "Trial", "seasons": ["2007 Spring", "2008 Fall"], "locationDbId": "23", "locationName": "Kenya", "programDbId": "27", "programName": "Drought Resistance Program A", "startDate": "2007-06-01", "endDate" : "2008-12-31", "studyType": "Trial", "active" : "true", "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } } , { "studyDbId": "345", "name": "Earlygenerationtesting", "trialDbId" : "7", "trialName" : "InternationalTrialA", "seasons": ["2007 Spring", "2008 Fall"], "locationDbId": "33", "locationName": "Zimbabwe", "programDbId": "58", "programName": "Drought Resistance Program B", "startDate": "2005-06-01", "endDate" : "2008-12-31", "studyType": "Trial", "active" : "true", "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } } ] } } ### Search Studies (POST) [POST /brapi/v1/studies-search] + Request (application/json) { "studyType" : "Trial", "studyNames" : ["Study A", "StydyB"], "studyLocations" : ["Kenya", "Zimbabwe"], "programNames": ["Test Program", "Program2"], "germplasmDbIds" : [ "CML123", "CWL123"], "trialDbIds" : [ "7", "8"], "observationVariableDbIds": ["CO-PH-123", "Var-123"] "active" : "true", "sortBy" : "studyDbId", "sortOrder" : "desc", "pageSize": 1000, "page": 0, } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data": [ { "studyDbId": "35", "name": "Earlygenerationtesting", "trialDbId" : "7", "trialName" : "InternationalTrialA", "studyType": "Trial", "seasons": ["2007 Spring", "2008 Fall"], "locationDbId": "23", "locationName": "Kenya", "programDbId": "27", "programName": "Drought Resistance Program A", "startDate": "2007-06-01", "endDate" : "2008-12-31", "studyType": "Trial", "active" : "true", "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } } , { "studyDbId": "345", "name": "Earlygenerationtesting", "trialDbId" : "1", "trialName" : "InternationalTrialA", "seasons": ["2005 Winter", "2006 Summer"], "locationDbId": "33", "locationName": "Zimbabwe", "programDbId": "58", "programName": "Drought Resistance Program B", "startDate": "2005-06-01", "endDate" : "2008-12-31", "studyType": "Trial", "active" : "true", "additionalInfo" : { "property1Name" : "property1Value", "property2Name" : "property2Value", "property3Name" : "property3Value" } } ] } } ## Study Details [/brapi/v1/studies/{studyDbId}] Scope: PHENOTYPING. Status: ACCEPTED. Implemented by: Germinate, GnpIS Notes: an additionalInfo field was added to provide a controlled vocabulary for less common data fields. Retrieve the information of the study required for field data collection More linked data: * observation variables: ```/brapi/v1/studies/{studyDbId}/observationVariables``` * germplasm: ```/brapi/v1/studies/{studyDbId}/germplasm``` * observation units: ```/brapi/v1/studies/{studyDbId}/observationUnits``` * layout: ```brapi/v1/studies/{studyDbId}/layout``` ###### Response data types | Variable | Datatype | Description | Required | | ----------------------- | --------------- | ------------------------------------------------------- | :------: | | studyDbId | string | string database identifier | Y | | studyName | string | Human readable name | Y | | studyType | string | Human readable type, must be listed in studyType call | | | studyDescription | string | Free text descritpion, can include some tracability | | | seasons | array of string | list of seasons the trials is running | | | trialDbId | string | Study trial database identifier | | | trialName | string | Study trial name | | | trialDbIds | array of string | Study trials database identifier (V1 non breaking change, trialDbId should be empty if this one is used) | | | startDate | string | Study start date (format YYYY-MM-DD) | | | endDate | string | Study end date (format YYYY-MM-DD) | | | active | boolean | Study active status (true/false) | | | license | string | License for data use. If using a known license like CC-BY, use the URI (https://creativecommons.org/licenses/by/4.0/) | | | location | object | Study location metadata object | Y | | location.locationDbId | string | Study location database identifier | Y | | location.name | string | Study location name | Y | | location.abbreviation | string | Study location abbreviation | | | location.countryCode | string | Study location ISO-3166 country code (ex: US, FR, etc.) | | | location.countryName | string | Study location country | | | location.instituteName | string | Study location institute/laboratory name | | | **deprecated** location.instituteAdress| string | **Use location.instituteAddress** | | | location.instituteAddress| string | Study location institute/laboratory address | | | location.latitude | number | Study location latitude | | | location.longitude | number | Study location longitude | | | location.altitude | number | Study location altitude in meters | | | location.additionalInfo | object | Additional arbitrary info on the study location | | | contacts | array of object | List of study contacts | | | contacts.contactDbId | string | Study contact database identifier | | | contacts.name | string | Study contact name | | | contacts.instituteName | string | Study contact institute name | | | contacts.email | string | Study contact email | | | contacts.type | string | Study contact type (ex: Coordinator, Scientist, etc.) | | | contacts.orcid | string | Study contact orcid identifier (http://orcid.org) | | | dataLinks | array of object | List of data links the study | | | dataLinks.type | string | Data link type | | | dataLinks.name | string | Data link name | | | dataLinks.url | string | Data link url | | | lastUpdate | object | last lastUpdate | | | lastUpdate.version | string | last version | | | lastUpdate.timestamp | string | timestamp of the last version ("2017-06-17T11:03:38-0800" (date, time, timezone)) | | | additionalInfo | object | Additional arbitrary info on the study, like objectives or publications | | | additionalInfo.publications | array of string | Additional info for publications | | ### Retrieve study details [GET /brapi/v1/studies/{studyDbId}] + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status": [], "datafiles": [] }, "result": { "studyDbId": 35, "studyName": "Earlygenerationtesting", "studyType": "Yield study", "studyDescription": "some free text description that could include scientific goal, some tracability and whatever makes sense" "seasons": [ "2005 Winter", "2008 Summer" ], "trialDbId": 57, "trialName": "International Yield Trial", "startDate": "2005-06-01", "endDate": "2008-12-31", "active": "true", "license": "https://creativecommons.org/licenses/by/4.0", "location": { "locationDbId": 1, "name": "Ibadan", "abbreviation": "IB", "countryCode": "NGA", "countryName": "Nigeria", "instituteName"; "INRA - GDEC", "instituteAddress"; "route foo, Clermont Ferrand, France", "latitude": -21.5, "longitude": 165.5, "altitude": 12, "additionalInfo": { "AnnualMeanRain": "value", "SoilDescription": "23", "property1Name": "property1Value", "property2Name": "property2Value" } }, "contacts": [ { "contactDbId": "C025", "name": "John Doe", "instituteName":"IRRI", "email": "j.doe@mail.com", "type": "Scientist", "orcid": "0000-0002-0607-8728" }, { "contactDbId": "C026", "name": "Dave Peters", "instituteName":"IRRI", "email": null, "type": null, "orcid": null } ], "dataLinks": [ { "type": "Image archive", "name": "image-archive12.zip", "url": "http://data.inra.fr/archive/multi-spect-flowering.zip" } ], "lastUpdate": { "version": "1.1", "timestamp": "2015-06-16T00:53:26Z" }, "additionalInfo": { "studyObjective": "Increase yield", "principalInvestigator": "Dr. Breeder", "property1Name": "property1Value", "property2Name": "property2Value", "publications": ["pmid:24039865287545"] } } } ## Study Observation Variables [/brapi/v1/studies/{studyDbId}/observationvariables] Scope: PHENOTYPING List all the observation variables measured in the study. Refer to the data type definition of variables in `/Specification/ObservationVariables/README.md`. ### Get Observation Variables By Study [GET /brapi/v1/studies/{studyDbId}/observationvariables] + Parameters + studyDbId (required, string, `ST012`) ... string database unique identifier + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [] }, "result": { "studyDbId": "123", "trialName": "myBestTrial", "data": [ { "observationVariableDbId": "CO_334:0100632", "name": "CT_M_C", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "trait": { "traitDbId": "CO_334:0100630", "name": "Canopy temperature" }, "method": null, "scale": null, "defaultValue": null }, { "observationVariableDbId": "CO_334:0100622", "name": "caro_spectro", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "synonyms": ["Carotenoid content by spectro"], "contextOfUse": ["Trial evaluation", "Nursery evaluation"], "growthStage": "mature", "status": "recommended", "xref": "TL_455:0003001", "institution": "", "scientist": "", "date": "2016-05-13", "language": "EN", "crop": "Cassava", "trait": { "traitDbId": "CO_334:0100620", "name": "Carotenoid content", "class": "physiological trait", "description": "Cassava storage root pulp carotenoid content", "synonyms": ["carotenoid content measure"], "mainAbbreviation": "CC", "alternativeAbbreviations": ["CCS"], "entity": "root", "attribute": "carotenoid", "status": "recommended", "xref": "TL_455:0003023" }, "method": { "methodDbId": "CO_334:0010320", "name": "Visual Rating:total carotenoid by chart_method", "class": "Estimation", "description": "Assessment of the level of yellowness in cassava storage root pulp using the tc chart", "formula": null, "reference": null }, "scale": { "scaleDbId": "CO_334:0100526", "name": "ug/g", "datatype": "Numeric", "decimalPlaces": 2, "xref": null, "validValues": { "min": 1, "max": 3, "categories": ["1=low", "2=medium", "3=high"] } }, "defaultValue": null } ] } } ### **Deprecated** Retrieve study observation variables [GET /brapi/v1/studies/{studyDbId}/observationVariables] + Parameters + studyDbId (required, string, `ST012`) ... string database unique identifier + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [] }, "result": { "studyDbId": "123", "trialName": "myBestTrial", "data": [ { "observationVariableDbId": "CO_334:0100632", "name": "CT_M_C", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "trait": { "traitDbId": "CO_334:0100630", "name": "Canopy temperature" }, "method": null, "scale": null, "defaultValue": null }, { "observationVariableDbId": "CO_334:0100622", "name": "caro_spectro", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "synonyms": ["Carotenoid content by spectro"], "contextOfUse": ["Trial evaluation", "Nursery evaluation"], "growthStage": "mature", "status": "recommended", "xref": "TL_455:0003001", "institution": "", "scientist": "", "date": "2016-05-13", "language": "EN", "crop": "Cassava", "trait": { "traitDbId": "CO_334:0100620", "name": "Carotenoid content", "class": "physiological trait", "description": "Cassava storage root pulp carotenoid content", "synonyms": ["carotenoid content measure"], "mainAbbreviation": "CC", "alternativeAbbreviations": ["CCS"], "entity": "root", "attribute": "carotenoid", "status": "recommended", "xref": "TL_455:0003023" }, "method": { "methodDbId": "CO_334:0010320", "name": "Visual Rating:total carotenoid by chart_method", "class": "Estimation", "description": "Assessment of the level of yellowness in cassava storage root pulp using the tc chart", "formula": null, "reference": null }, "scale": { "scaleDbId": "CO_334:0100526", "name": "ug/g", "datatype": "Numeric", "decimalPlaces": 2, "xref": null, "validValues": { "min": 1, "max": 3, "categories": ["1=low", "2=medium", "3=high"] } }, "defaultValue": null } ] } } ## Study Germplasm Details [/brapi/v1/studies/{studyDbId}/germplasm] Scope: PHENOTYPING ### Study Germplasm Details [GET /brapi/v1/studies/{studyDbId}/germplasm{?pageSize}{?page}] + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [], }, "result": { "studyDbId": 123, "trialName": "myBestTrial", "data": [ { "germplasmDbId": "382", "entryNumber": "1", "germplasmName": "Pahang", "pedigree": "TOBA97/SW90.1057", "seedSource": "SS1", "accessionNumber": "ITC0609", "germplasmPUI": "http://www.crop-diversity.org/mgis/accession/01BEL084609", "synonyms": ["01BEL084609"] }, { "germplasmDbId": "394", "entryNumber": "2", "germplasmName": "Pahang", "pedigree": "TOBA97/SW90.1057", "seedSource": "SS2", "accessionNumber": "ITC0727", "germplasmPUI": "http://www.crop-diversity.org/mgis/accession/01BEL084727", "synonyms": [ "01BEL084727"] } ] } } ## List Observation Levels [/brapi/v1/observationlevels] Call to retrieve the list of supported observation levels. Observation levels indicate the granularity level at which the measurements are taken. The values are used to supply the `observationLevel` parameter in the observation unit details call. ### **Deprecated** List observation levels [GET /brapi/v1/observationLevels?&pageSize={pageSize}&page={page}] + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : ["plant", "plot"] } } ### Get Observation Levels [GET /brapi/v1/observationlevels{?pageSize}{?page}] + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : ["plant", "plot"] } } ## Observation Unit Details [/brapi/v1/studies/{studyDbId}/observationunits] The main API call for field data collection, to retrieve all the observation units within a study. Scope: PHENOTYPING ### Get all observation units [GET /brapi/v1/studies/{studyDbId}/observationunits{?observationLevel}{?pageSize}{?page}] + Parameters + studyDbId (required, string, `abc123`) ... The study these observation units are related to. + observationLevel (required, string, `plot`) ... The granularity level of observation units. Either `plotNumber` or `plantNumber` fields will be relavant depending on whether granularity is plot or plant respectively. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result" : { "data" : [ { "observationUnitDbId": "abc-123", "observationUnitName": "Test-2016-location-34-575", "observationLevel": "plot", "germplasmDbId": "1", "germplasmName": "IR-8", "pedigree": "IR-8-FP/IR-8-MP", "entryNumber": "1", "entryType": "Test entry", "plotNumber": "1", "plantNumber" : "0", "blockNumber" : "1", "X" : "1", "Y" : "1", "replicate": "1", "observationUnitXref":[ {"source": "biosampleEBI", "id": "SAMEA179865230"}, {"source": "gnpis.lot", "id": "INRA:CoeSt6 _SMH03"}, {"source": "kernelDB", "id": "239865"} ], "observations": [ { "observationDbId": "153453453", "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null }, { "observationDbId": "23453454345", "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null } ] }, { "observatioUnitDbId": "abc-456", "observationUnitName": "Test-2016-location-34-456", "observationLevel": "plot", "germplasmDbId": "2", "germplasmName": "IR-9", "pedigree": "IR-9-FP/IR-9-MP", "enrtyNumber": "2", "entryType": "Check entry", "plotNumber": "2", "plantNumber" : "0", "blockNumber" : "2", "X" : "1", "Y" : "2", "replicate": "1", "observations": [ { "observationDbId": "3", "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null }, { "observationDbId": "4", "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null } ] } ] } } ### **Deprecated** Save Observation Unit Phenotypes [POST /brapi/v1/studies/{studyDbId}/observationunits?format={format}] This call has been deprecated in V1.1. Use instead: "PUT /studies/{studyDbId}/observationunits" and "PUT /studies/{studyDbId}/observationunits/zip" + Parameters + format ... (default is JSON, but can be zip) In case where JSON data is zipped for faster transfer speed (as in the case of the IRRI handheld implementation), the zipped JSON file will be listed in datafiles. The zipped file contains a JSON file with the same structure as the BrAPI call. + Request (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [], "datafiles": [ "all_images.zip" ] }, "result" : { "transactionDbId": "83748382938", "commit" : "true/false", "data" : [ { "observatioUnitDbId": "abc-123", "studyDbId": 2, "observations": [ { "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "11" }, { "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "111" }, { "observationVariableDbId": "51497", "observationVariableName": "image", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "myimage1.jpg" } ] }, { "observatioUnitDbId": "abc-456", "studyDbId": 3, "observations": [ { "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "22" }, { "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "222" }, { "observationVariableDbId": "51497", "observationVariableName": "image", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": "myimage2.jpg" } ] } ] } } + Response 200 (application/json) + Response 400 (application/json) { "metadata": { "status": [ { "code":"42", "message": "Could not update values for Observation Units" } ] } } ### Save Observation Unit Phenotypes [PUT /brapi/v1/studies/{studyDbId}/observationunits] Use this call for uploading new Observations as JSON to a system. Note: If 'observationUnitDbId' or 'observationDbId' is populated, they should be considered updates to existing records. If an existing record of that DbId is not found, the document should be treated as new records and assigned new DbIds. If 'observationUnitDbId' or 'observationDbId' is un-populated (empty string or null) the document should be treated as new records and assigned new DbIds. + Parameters + studyDbId (required, string, `abc123`) ... The study these observation units are related to. + Request (application/json) [ { "observationUnitDbId": "", // ignored if new "observationUnitName": "Test-2016-location-34-575", "observationLevel": "plot", "germplasmDbId": "1", "germplasmName": "IR-8", "pedigree": "IR-8-FP/IR-8-MP", "entryNumber": "1", "entryType": "Test entry", "plotNumber": "1", "plantNumber" : "0", "blockNumber" : "1", "X" : "1", "Y" : "1", "replicate": "1", "observationUnitXref":[ {"source": "biosampleEBI", "id": "SAMEA179865230"}, {"source": "gnpis.lot", "id": "INRA:CoeSt6 _SMH03"}, {"source": "kernelDB", "id": "239865"} ], "observations": [ { "observationDbId": "", // ignored if new "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null }, { "observationDbId": "", // ignored if new "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null } ] }, { "observationUnitDbId": "", // ignored if new "observationUnitName": "Test-2016-location-34-575", "observationLevel": "plot", "germplasmDbId": "1", "germplasmName": "IR-8", "pedigree": "IR-8-FP/IR-8-MP", "entryNumber": "1", "entryType": "Test entry", "plotNumber": "1", "plantNumber" : "0", "blockNumber" : "1", "X" : "1", "Y" : "1", "replicate": "1", "observationUnitXref":[ {"source": "biosampleEBI", "id": "SAMEA179865230"}, {"source": "gnpis.lot", "id": "INRA:CoeSt6 _SMH03"}, {"source": "kernelDB", "id": "239865"} ], "observations": [ { "observationDbId": "", // ignored if new "observationVariableDbId": "18020", "observationVariableName": "Plant_height", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null }, { "observationDbId": "", // ignored if new "observationVariableDbId": "51496", "observationVariableName": "GW100_g", "collector" : "Mr. Technician", "observationTimeStamp" : "2015-06-16T00:53:26Z", "value": null } ] } ] + Response 200 (application/json) + Body { "metadata": { "status": [ { "code":"1", "message": "Upload Successful" } ] }, "results": { "observationUnitDbIds" : [ "123abc", "456def" ] } } + Response 400 (application/json) { "metadata": { "status": [ { "code":"42", "message": "Could not update values for Observation Units" } ] } } + Request (application/json) + Headers Content-Encoding: gzip + Body H4sIAAAAAAAA/+1VXW+bMBR976+w/BwaA4WmvKXrxyItUdSwtls1RUBuiVVjI0MyVVX/+wwdrDEEVdM0tRJ+Aa7POb5f5iKE0N0B+r2e6rdiYRFmILdBTgX/yml+Fk5W2EMYD9BwiGjMhYQVoveIw89O4ixIoCD6kOWGRUzXYCIqdw37yHCOHTzYy/8CW2AFOWUi13ExyCRlQZZUrpl7EZUPkytjpINSWNFYQr1vXMyH5XM616HAc/k42yQhyNbzyn3/Ma3jRaWlcaIKpkNFecyrfaQARAeEKoEPrwANhdt287d2s4SUUVURaPVGq+athHvs3e1givWEM7GRUakRUpEFKvFwfjpR7YJpWZ3FeHo+No9PRq5j2QQ/Dzo1Yp7S7LCseiUwmV2NvU8CFrmLlovpZ2IrEdSp8gCSAzs7/SNi2YUD+HmH9mN/zJkitUTbsOi8N1+XNvJ1IGkQMqgbe0QsvQu6eFW7z4tOWq6Bxmv99tT0SDAGUS5eWmkqD5EP0ZrTiAb8DUf6NFEFUdUu6ep6OwZxDdP1CfEc27Pc7/tEtgHbFF7yDWMNRFt3NEutO/NPk+6YRyfuXyT98sYkZBl/sHzv3of661Ud+vHQj4d+PKB+PLyH31U/HtpP+9/j4eDl+xeKyAPWSQwAAA== + Response 200 (application/json) + Body { "metadata": { "status": [ { "code":"1", "message": "Upload Successful" } ] }, "results": { "observationUnitDbIds" : [ "123abc", "456def" ] } } + Response 400 (application/json) { "metadata": { "status": [ { "code":"42", "message": "Could not update values for Observation Units" } ] } } ### Save Observation Unit Phenotypes (zip file) [POST /brapi/v1/studies/{studyDbId}/observationunits/zip] Use this call for uploading new Observations as a Batched Zip File to a system. Note: If 'observationUnitDbId' or 'observationDbId' is populated, they should be considered updates to existing records. If an existing record of that DbId is not found, the document should be treated as new records and assigned new DbIds. If 'observationUnitDbId' or 'observationDbId' is un-populated (empty string or null) the document should be treated as new records and assigned new DbIds. + Parameters + studyDbId (required, string, `abc123`) ... The study these observation units are related to. + Request (application/zip) + Body Zip file data with observation unit data + Response 200 (application/json) + Body { "metadata": { "status": [ { "code":"1", "message": "Upload Successful" } ] }, "results": { "observationUnitDbIds" : [ "123abc", "456def" ] } } + Response 400 (application/json) { "metadata": { "status": [ { "code":"42", "message": "Could not update values for Observation Units" } ] } } ## Study Observation Units as a Table [/brapi/v1/studies/{studyDbId}/table] Scope: PHENOTYPING. Status: ACCEPTED. Implemented in Cassavabase, HIDAP and Germinate. Notes: Implementation target date: after PAG2016 Retrieve the details of the study required for field data collection. Includes actual trait data. ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |studyDbId|Long|internal DB id || |metadata|object|pagination, status, datafiles|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list of objects||Y| |datafiles|list||Y| |observationVariableDbId|Long | internal DB id for the traits measured || |observationVariableName|String| name of variable|| |data| object| List of lists, specifying the plotDbId, block, rep, germplasmDbId, and the phenotypic values|| ### Retrieve study Observation Units as table [GET /brapi/v1/studies/{studyDbId}/table{?format}] + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + format (optional, string, `tsv`) ... The format parameter will cause the data to be dumped to a file in the specified format. Currently, tsv and csv are supported. + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [] }, "result" : { "headerRow": [ "year","studyDbId","studyName","locationDbId","locationName","germplasmDbId","germplasmName","observationUnitDbId","plotNumber","replicate","blockNumber", "observationTimestamp", "entryType", "X", "Y"], "observationVariableDbIds": [ "variable1DbId", "variable2DbId", "variable3DbId"], // for linking "observationVariableNames": [ "plant height", "fruit weight", "root weight" ], // for display // the observationNames will follow the columns defined in the headerRow "data" : [ [1, 1, 1, "CIP1", ...], [2, 1, 1, "CIP2", ...] ] } } ### Save study Observation Units as table [POST /brapi/v1/studies/{studyDbId}/table] Images can optionally be saved using this call by providing a zipped file of all images in the datafiles. The physical zipped file should be transferred as well in the mulit-part form data. Scope: PHENOTYPING + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + Request { "metadata": { "pagination" : { "pageSize":20, "currentPage":0, "totalCount":2, "totalPages":1 }, "status" : [], "datafiles": [ "all_images.zip" ] }, "result" : { "headerRow": [ "observationUnitDbId", "collector", "observationTimestamp", "variable1Id", "variable2Id", "variable3Id" ], "observationVariableDbIds": [ "variable1DbId", "variable2DbId", "variable3DbId", "imagevariable1DbId" ], "data" : [ [1, "Mr. Technician1", "2015-06-16T10:00:00Z", "variable1Value", "variable2Value", "variable3Value", "image1.jpg" ], [2, "Mr. Technician2", "2015-06-16T11:00:01Z", "variable1Value", "variable2Value", "variable3Value", "image2.jpg" ] ] } } + Response 200 ## Plot Layout Details [/brapi/v1/studies/{studyDbId}/layout] Scope: PHENOTYPING. Status: ACCEPTED. Implementation target date: PAG2016 Notes: the plot information. Retrieve the plot layout of the study with id {id}. ### Retrieve plot layout details [GET /brapi/v1/studies/{studyDbId}/layout{?pageSize}{?page}] + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + 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": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [] }, "result" : { "data" : [ { "studyDbId": 1, "observationUnitDbId": 11, "observationUnitName": "ZIPA_68_Ibadan_2014", "observationLevel": "plot", "replicate": 1, "germplasmDbId": 143, "germplasmName": "ZIPA_68", "blockNumber": 1, "X": 20, "Y": 22, "entryType": "check/test/filler", "additionalInfo" : { } } ] } } ## Get Observation Units by observation variable ids [/brapi/v1/studies/{studyDbId}/observations] Scope: CORE. Status: ACCEPTED. Implementation target date: PAG2016 Retrieve all plots where there are measurements for the given observation variables. observationTimestamp should be ISO8601 format with timezone: YYYY-MM-DDThh:mm:ss+hhmm ### Get Observation Units by observation variable ids [GET /brapi/v1/studies/{studyDbId}/observations{?observationVariableDbIds}{?pageSize}{?page}] + Parameters + studyDbId (required, string, `1`) ... Identifier of the study. Usually a number, could be alphanumeric. + observationVariableDbIds (required, array, `393939,393938`) ... Numeric `id` of that variable (combination of trait, unit and method) + 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": 1000, "currentPage": 0, "totalCount": 1, "totalPages": 1 }, "status": [], "datafiles": [], } "result" : { "data" : [ { "studyDbId": "1", "obserationDbId": "3383838", "observationUnitDbId": 11, "observationUnitName": "ZIPA_68_Ibadan_2014", "observationLevel" : "plot", "observationVariableDbId" : 393939, "observationVariableName" : "Yield", "observationTimestamp" : "2015-11-05T15:12:56+0100", "uploadedBy" : "dbUserId", "operator" : "Jane Doe", "germplasmDbId" : 8383, "germplasmName": 143, "value" : 5 } ] } } # Group Phenotypes API to retrieve and submit data (phenotypes, environment variables) from studies. While the study calls focus on one study, calls in this section are for cross-study phenotypic data retrieval and submission. ## Phenotype Search [/brapi/v1/phenotypes-search] Scope: PHENOTYPING. Status: ACCEPTED. Returns a list of observationUnit with the observed Phenotypes. See Search Services for additional implementation details. Implemented for GnpIS and PHIS data (https://urgi.versailles.inra.fr/ws/webresources/brapi/v1/phenotypes). Use case: this section allows to get a dataset from multiple studies. It allows to integrate data from several databases. Refactor note : This call allows to get and integrate portions of multiple phenotyping data matrixes. A proposed evolution allowed to get a list of single observations, this functionality is still possible with this call by specifybing the observation variable, see below. Example Use cases: - Study a panel of germplasm accross multiple studies, search parameters : {"germplasmDbIds" : [ "Syrah", "34Mtp362" ]} - Get all data for a specific study : {"studyDbIds" : [ "383" ]} - Get simple atomic phenotyping values : {"germplasmDbIds" : [ "Syrah", "34Mtp362" ], "observationVariableDbIds" : [ "CO_345:0000043"]} - Study Locations for adaptation to climat change : {"locationDbIds" : [ "383838", "MONTPELLIER" ], "germplasmDbIds" : [ "all ids for a given species"]} - Find phenotypes that are from after a certain timestamp ###### Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |observationUnitDbId|String|internal DB id, can be a primary key, a URI or any other ID, must be unique within the calls | Y | |studyDbId|String|internal DB id , can be a primary key, a URI or any other ID| Y | |studyName | string ||| |studyLocationDbId| string | internal DB id , can be a primary key, a URI or any other ID |Y| |studyLocation|string| Location name || |observationLevel | string | level of this observation unit. Its ID is the observationUnitDbId|| |observationLevels|string| Concatenation of the levels of this observationUnit. Used to handle non canonical level structures. Format levelType:levelID,levelType:levelID || |plotNumber|string| Plot level ID. Null if not relevant because the observation unit is a higher level || |plantNumber|string| Plant Level ID || |blockNumber|string| Block Level ID || |replicate|string| replicate level ID || |programName|string||| |germplasmDbId|Long|internal DB id , can be a primary key, a URI or any other ID|Y| |germplasmName|string| Display name for the germplasm. MCPD Name field|| |X,Y|string|Relative position in the study. Can be row/colmun number, line/rootstock, meters, etc...|| |treatments|array of objects|list of all the factors applied to the observation unit : fertilizer, inoculation, irrigation, etc...|| |treatments.factor|string|the type of treatment/factor. EG: fertilizer, inoculation, irrigation, etc...|| |treatments.modality|string|the treatment/factor descritpion. EG: low fertilizer, yellow rust inoculation, high water, etc...|| |observationUnitXref |array of objects|Xref, IDs of this observation Unit in this database or other database. Handle different IDs of your individuals/plant material/seed Lot| | |observationUnitXref.source |string| the source/name space of the ID, for known databases use : biosampleEBI, biosampleNCBI | Y | |observationUnitXref.id |string| ID | Y | |observations|array of objects|At least one observation. See below for details on the content.|Y| |observations.observationDbId|string| ID or PUI (DOI, URI, LSID)|| |observations.observationVariableDbId|string| ID or PUI (DOI, URI, LSID)|Y| |observations.observationVariableName | string | Display name|| |observations.season|string| this can be considered as a label to group data within a multiyear study. It can be a year, season, Phenotyping campain, a period accross multiple years or a list of some years || |observations.value|string||| |observations.observationTimeStamp|string|ISO format "2006-07-03T10:00:38-0800"|| |observations.collector|string| Person or team who has made the observation|| ### Phenotype Search [POST /brapi/v1/phenotypes-search] observationTimeStamp : Iso Standard 8601. observationValue data type inferred from the ontology + Request (application/json) { "germplasmDbIds" : [ "Blabla", "34Mtp362" ], // (optional) The name or synonym of external genebank accession identifiers "observationVariableDbIds" : [ "37373", "CO_321:00000234"], // (optional) The IDs of traits, could be ontology ID, database ID or PUI "studyDbIds" : [ "383", "2929", "WHEAT_NETWK_2016_MONTPELLIER" ], // (optional) The database ID / PK of the studies search parameter "locationDbIds" : [ "383838", "MONTPELLIER" ], // (optional) locations these traits were collected "programDbIds" : [ "3838", "Drought_resistance_CG_2020" ], // (optional) list of programs that have phenotyped this trait "seasonDbIds" : [ "338", "2010", "1956-2014", "2002-2003-2004", "2007 Spring" ], // (optional) The year or Phenotyping campaign of a multiannual study (trees, grape, ...) "observationLevel" : "plot", // (optional) The type of the observationUnit. Returns only the observaton unit of the specified type; the parent levels ID can be accessed through observationUnitStructure. "observationTimeStampRange" : ["2015-06-16T00:53:26-0800","2015-06-18T00:53:26-0800"] // (optional) Array fixed length of 2. First item is the Start Timestamp, second item is the End Timestamp. "pageSize" : 100, // (optional) The size of the pages to be returned. Default is `1000`. "page" : 1, // (optional) Which result page is requested } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 100, "currentPage": 1, "totalCount": 102, "totalPages": 2 }, "status": [], "datafiles": [] }, "result": { "data": [ { "observationUnitDbId": "2016-Maugio-34-575-abc-123", "observationLevel": "plot", "observationLevels": "bloc:2,subBloc:1,plot:2016-Maugio-34-575-abc-123", "plotNumber": "2016-Maugio-34-575-abc-123", "plantNumber" : null, "blockNumber" : "2", "replicate": null, "observationUnitName": "2016-Maugio-34-575", "germplasmDbId": "doi:10.155454/12349537E12", "germplasmName": "IR-8", "studyDbId": "YieldStudy2015-5", "studyName": "Yield wheat 2015", "studyLocationDbId": "mtp-north-32", "studyLocation": "Montpellier", "programName": "Whealbi", "X": "5", "Y": "15", "entryType": null, "entryNumber": null, "treatments": [ { "factor": "water regimen", "modality": "water deficit" } ], "observationUnitXref":[ {"source": "biosampleEBI", "id": "SAMEA179865230"}, {"source": "gnpis.lot", "id": "INRA:CoeSt6 _SMH03"}, {"source": "kernelDB", "id": "239865"} ], "observations": [ { "observationDbId": "153453453", "observationVariableDbId": "CO_321:0000045", "observationVariableName": "Plant_height", "observationTimeStamp": "2015-06-16T00:53:26-0800", "season": "2015", "collector": "Mr. Technician", "value": "45" }, { "observationDbId": "23453454345", "observationVariableDbId": "CO_321:0000996", "observationVariableName": "GW100_g", "observationTimeStamp": "2015-06-16T00:53:26-0800", "season": "2015", "collector": "Mr. Technician", "value": "3" } ] }, { "observationUnitDbId": "45204", "observationLevel": "plant", "observationLevels": null, "plotNumber": null, "plantNumber" : "45204", "blockNumber" : null, "replicate": "2", "observationUnitName": "2010-Cornell-37-99", "germplasmDbId": "doi:10.155499/12349537E00", "germplasmName": "ZE-45", "studyDbId": "YieldStudy2010-5", "studyName": "Yield wheat 2010", "studyLocationDbId": "88484", "studyLocation": "Cornell", "programName": "Wheat for futur", "X": null, "Y": null, "entryType": null, "entryNumber": null, "treatments": [], "observations": [ { "observationDbId": "153453453", "observationVariableDbId": "CO_321:0000045", "observationVariableName": "Plant_height", "observationTimeStamp": "2010-06-16T00:53:26-0800", "season": "2010", "collector": "Mr. Technician", "value": "45" }, { "observationDbId": "23453454345", "observationVariableDbId": "CO_321:0000996", "observationVariableName": "GW100_g", "observationTimeStamp": "2010-06-16T00:53:26-0800", "season": "2010", "collector": "Mr. Technician", "value": "3" } ] } ] } } # Group Traits Trait Ontology Calls. API to retrieve list of traits and their associated variables. ## List all Traits [/brapi/v1/traits] Scope: CORE. Status: ACCEPTED. Implemented by: Germinate, Cassavabase Call to retrieve a list of traits available in the system and their associated variables. ### List all traits [GET /brapi/v1/traits{?pageSize}{?page}] + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result" : { "data" : [ { "traitDbId": "123", "traitId": "CO:123000007", "name": "Plant Height", "description": "Description of Plant Height", "observationVariables": [ "CO_334:0100121", "CO_334:0100122", "CO_334:0100123" ], "defaultValue": null }, { "traitDbId": "123", "traitId": "CO_334:0100620", "name": "Carotenoid content", "description": "Cassava storage root pulp carotenoid content", "observationVariables": [ "CO_334:0100621", "CO_334:0100622", "CO_334:0100623" ], "defaultValue": null } ] } } ## Trait Details [/brapi/v1/traits/{traitDbId}] Scope: CORE. Status: ACCEPTED. Implemented by: Germinate Retrieve the variables associated to a trait ### Retrieve trait details by id [GET /brapi/v1/traits/{traitDbId}] + Parameters + traitDbId (required, string, `464`) ... Id of the trait to retrieve details of. + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status": [], "datafiles": [] }, "result": { "traitDbId": "123", "traitId": "CO:123000007", "name": "Plant Height", "description": "Description of Plant Height", "observationVariables": [ "CO_334:0100121", "CO_334:0100122", "CO_334:0100123" ], "defaultValue": null } } # Group Observation Variables Implemented by: GnpIS API to retrieve list and details of observation variables. An observation variable is composed by the unique combination of one Trait, one Method and one Scale. ## Observation variable data response `required` means the key has to be provided, but the value may be null. Variable | Required | Type | Description ------------------------------ | :------: | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- observationVariableDbId | Y | string | Variable unique identifier name | Y | string | Variable name (usually a short name) ontologyDbId | Y | string | Variable ontology unique identifier ontologyName | Y | string | Variable ontology name (usually a short name) synonyms | | array of string | Other variable names contextOfUse | | array of string | Indication of how trait is routinely used. (examples: ["Trial evaluation", "Nursery evaluation"]) growthStage | | string | Growth stage at which measurement is made (examples: "flowering") status | | string | Variable status. (examples: "recommended", "obsolete", "legacy", etc.) xref | | string | Cross reference of the variable term to a term from an external ontology or to a database of a major system. institution | | string | Name of institution submitting the variable scientist | | string | Name of scientist submitting the variable. date | | string | Date of submission of the variable (ISO 8601). language | | string | 2 letter ISO code for the language of submission of the variable. crop | | string | Crop name (examples: "Maize", "Wheat") trait | Y | object | Trait metadata trait.traitDbId | Y | string | Trait unique identifier trait.name | Y | string | Trait name (usually a short name) trait.class | | string | Trait class. (examples: "morphological trait", "phenological trait", "agronomical trait", "physiological trait", "abiotic stress trait", "biotic stress trait", "biochemical trait", "quality traits trait", "fertility trait", etc.) trait.description | | string | Trait description. trait.synonyms | | array of string | Other trait names trait.mainAbbreviation | | string | Main abbreviation for trait name. (examples: "Carotenoid content" => "CC") trait.alternativeAbbreviations | | array of string | Other frequent abbreviations of the trait, if any. These abbreviations do not have to follow a convention. If several aternative abbreviations, separate with commas. trait.entity | | string | A trait can be decomposed as "Trait" = "Entity" + "Attribute", the entity is the part of the plant that the trait refers to e.g., for "grain colour", entity = "grain" trait.attribute | | string | A trait can be decomposed as "Trait" = "Entity" + "Attribute", the attribute is the observed feature (or characteristic) of the entity e.g., for "grain colour", attribute = "colour" trait.status | | string | Trait status (examples: "recommended", "obsolete", "legacy", etc.) trait.xref | | string | Cross reference of the trait to an external ontology or database term e.g., Xref to a trait ontology (TO) term method | Y | object | Method metadata method.methodDbId | | string | Method unique identifier method.name | | string | Method name (usually a short name) method.class | | string | Method class (examples: "Measurement", "Counting", "Estimation", "Computation", etc. method.description | | string | Method description. method.formula | | string | For computational methods i.e., when the method consists in assessing the trait by computing measurements, write the generic formula used for the calculation method.reference | | string | Bibliographical reference describing the method. scale | Y | object | Scale metadata scale.scaleDbId | | string | Unique identifier of the scale. If left blank, the upload system will automatically generate a scale ID. scale.name | | string | Name of the scale scale.class | | string | Class of the scale, entries can be "Numerical", "Nominal", "Ordinal", "Text", "Code", "Time", "Duration" scale.decimalPlaces | | numeric | For numerical, number of decimal places to be reported scale.xref | | string | Cross reference to the scale, for example to a unit ontology such as UO or to a unit of an external major database scale.validValues.min | | numeric | Minimum value (used for data capture control) for numerical and date scales scale.validValues.max | | numeric | Maximum value (used for field data capture control). scale.validValues.categories | | array of string | List of possible values and their meaning (examples: ["0=low", "1=medium", "2=high"] defaultValue | Y | string | Variable default value. (examples: "red", "2.3", etc.) ## Ontology data response `required` means the key has to be provided, but the value may be null. Variable | Required | Type | Description ------------ | :------: | ------ | ----------------------------------------------- ontologyDbId | Y | string | Ontology database unique identifier ontologyName | Y | string | Ontology name authors | | string | Ontology's list of authors (no specific format) version | | string | Ontology version (no specific format) copyright | | string | Ontology copyright licence | | string | Ontology licence ## Variable data type list [/brapi/v1/variables/datatypes] Call to retrieve a list of data types the variable can have. ### Variable data type list [GET /brapi/v1/variables/datatypes{?pageSize}{?page}] + 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": 1000, "currentPage": 0, "totalCount": 6, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data": ["Numeric", "Categorical", "Date", "Text", "Picture", "Boolean"] } } ## Variable list [/brapi/v1/variables] Scope: CORE. Status: ACCEPTED. Call to retrieve a list of observationVariables available in the system. ### Variable list [GET /brapi/v1/variables{?page}{?pageSize}{?traitClass}] + 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`. + traitClass (optional, string, `Phenological`) ... Variable's trait class (phenological, physiological, morphological, etc.) + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data": [{ "observationVariableDbId": "CO_334:0100632", "name": "CT_M_C", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "trait": { "traitDbId": "CO_334:0100630", "name": "Canopy temperature" }, "method": null, "scale": null, "defaultValue": null }, { "observationVariableDbId": "CO_334:0100622", "name": "caro_spectro", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "synonyms": ["Carotenoid content by spectro"], "contextOfUse": ["Trial evaluation", "Nursery evaluation"], "growthStage": "mature", "status": "recommended", "xref": "TL_455:0003001", "institution": "", "scientist": "", "submissionTimestamp": "2016-05-13T17:43:11+0100", "language": "EN", "crop": "Cassava", "trait": { "traitDbId": "CO_334:0100620", "name": "Carotenoid content", "class": "physiological trait", "description": "Cassava storage root pulp carotenoid content", "synonyms": ["carotenoid content measure"], "mainAbbreviation": "CC", "alternativeAbbreviations": ["CCS"], "entity": "root", "attribute": "carotenoid", "status": "recommended", "xref": "TL_455:0003023" }, "method": { "methodDbId": "CO_334:0010320", "name": "Visual Rating:total carotenoid by chart_method", "class": "Estimation", "description": "Assessment of the level of yellowness in cassava storage root pulp using the tc chart", "formula": null, "reference": null }, "scale": { "scaleDbId": "CO_334:0100526", "name": "ug/g", "datatype": "Numeric", "decimalPlaces": 2, "xref": null, "validValues": { "min": 1, "max": 3, "categories": ["1=low", "2=medium", "3=high"] } }, "defaultValue": null }] } } ## Variable details [/brapi/v1/variables/{observationVariableDbId}] Scope: CORE. Status: ACCEPTED. Retrieve variable details ### Variable details by id [GET /brapi/v1/variables/{observationVariableDbId}] + Parameters + observationVariableDbId (required, string, `CO_334:0100622`) ... string id of the variable + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status": [], "datafiles": [] }, "result": { "observationVariableDbId": "CO_334:0100622", "name": "caro_spectro", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "synonyms": ["Carotenoid content by spectro"], "contextOfUse": ["Trial evaluation", "Nursery evaluation"], "growthStage": "mature", "status": "recommended", "xref": "TL_455:0003001", "institution": "", "scientist": "", "submissionTimestamp": "2016-05-13T15:43:41+0100", "language": "EN", "crop": "Cassava", "trait": { "traitDbId": "CO_334:0100620", "name": "Carotenoid content", "class": "physiological trait", "description": "Cassava storage root pulp carotenoid content", "synonyms": ["carotenoid content measure"], "mainAbbreviation": "CC", "alternativeAbbreviations": ["CCS"], "entity": "root", "attribute": "carotenoid", "status": "recommended", "xref": "TL_455:0003023" }, "method": { "methodDbId": "CO_334:0010320", "name": "Visual Rating:total carotenoid by chart_method", "class": "Estimation", "description": "Assessment of the level of yellowness in cassava storage root pulp using the tc chart", "formula": null, "reference": null }, "scale": { "scaleDbId": "CO_334:0100526", "name": "ug/g", "dataType": "Numeric", "decimalPlaces": 2, "xref": null, "validValues": { "min": 1, "max": 3, "categories": ["1=low", "2=medium", "3=high"] } }, "defaultValue": null } } ## Variable search [/brapi/v1/variables-search] Scope: CORE. Status: ACCEPTED. Search observation variables. See Search Services for additional implementation details. ### Variable search [POST /brapi/v1/variables-search] + Request (application/json) { "page": 0, "pageSize": 2, "observationVariableDbIds" : ["obs-variable-id1", "obs-variable-id1"], "ontologyXrefs" : ["CO:123", "CO:456"], "ontologyDbIds" : ["CO_334:0100632"], "methodDbIds" : ["method-1", "method=2"], "scaleDbIds" : ["scale-1", "scale-2"], "names" : ["caro_spectro"], "datatypes" : ["numeric"], "traitClasses" : ["Phenological", "Physiological"] } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 2, "currentPage": 0, "totalCount": 300, "totalPages": 150 }, "status": [], "datafiles": [] }, "result": { "data": [{ "observationVariableDbId": "CO_334:0100632", "name": "CT_M_C", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "trait": { "traitDbId": "CO_334:0100630", "name": "Canopy temperature" }, "method": null, "scale": null, "defaultValue": null }, { "observationVariableDbId": "CO_334:0100622", "name": "caro_spectro", "ontologyDbId": "CO_334", "ontologyName": "Cassava", "synonyms": ["Carotenoid content by spectro"], "contextOfUse": ["Trial evaluation", "Nursery evaluation"], "growthStage": "mature", "status": "recommended", "xref": "TL_455:0003001", "institution": "", "scientist": "", "submissionTimestamp": "2016-05-13T23:21:56+0100", "language": "EN", "crop": "Cassava", "trait": { "traitDbId": "CO_334:0100620", "name": "Carotenoid content", "class": "physiological trait", "description": "Cassava storage root pulp carotenoid content", "synonyms": ["carotenoid content measure"], "mainAbbreviation": "CC", "alternativeAbbreviations": ["CCS"], "entity": "root", "attribute": "carotenoid", "status": "recommended", "xref": "TL_455:0003023" }, "method": { "methodDbId": "CO_334:0010320", "name": "Visual Rating:total carotenoid by chart_method", "class": "Estimation", "description": "Assessment of the level of yellowness in cassava storage root pulp using the tc chart", "formula": null, "reference": null }, "scale": { "scaleDbId": "CO_334:0100526", "name": "ug/g", "datatype": "Numeric", "decimalPlaces": 2, "xref": null, "validValues": { "min": 1, "max": 3, "categories": ["1=low", "2=medium", "3=high"] } }, "defaultValue": null }] } } ## Variable ontology list [/brapi/v1/ontologies] Scope: CORE. Status: ACCEPTED. Call to retrieve a list of observation variable ontologies available in the system. ### Variable ontology list [GET /brapi/v1/ontologies{?page}{?pageSize}] + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data": [ { "ontologyDbId": "CO_334", "ontologyName": "Wheat ontology", "authors": "J. Snow, H. Peterson", "version": "v1.2", "description": "developped for European genetic studies projects", "copyright": "© 2016, INRA", "licence": "CC BY-SA 4.0" }, { "ontologyDbId": "CO_335", "ontologyName": "Rice ontology", "authors": "J. Doe", "description": "developped for IRRI and amended with partners needs", "version": "v2", "copyright": null, "licence": null } ] } } # Group Genome Maps Retrieving genetic or physical maps - type: [Genetic | Physical] - unit: [cM | Mb] - linkageGroup: may be scaffold (i.e. linkageGroupCount may consist of chromosomes or scaffolds or a combination of the two) - For genetic maps, map naming convention should tell whether it is a consensus or mapping population (name of population) map for genetic maps - For physical maps, map naming convention should tell whether it is a reference genome (name of line) or pan-genome ## Genome Map [/brapi/v1/maps] Status: ACCEPTED Implemented by: Germinate, Cassavabase Used by: Flapjack Get list of maps do we need list of parents and specify mapping population? ### Get list of maps [GET /brapi/v1/maps{?species}{?pageSize}{?page}{?type}] + Parameters + species (optional, string, `SomeSpecies`) ... Species name + type (optional, string, `Genetic`) ... Type of map + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data" : [ { "mapDbId": "1", "name": "Some Map", "species": "Some species", "type": "Genetic", "unit": "cM", "publishedDate": "2008-04-16", "markerCount": 1000, "linkageGroupCount": 7, "comments": "This map contains ..." }, { "mapDbId": "2", "name": "Some Other map", "species": "Some Species", "type": "Genetic", "unit": "cM", "publishedDate": "2009-01-12", "markerCount": 1501, "linkageGroupCount": 7, "comments": "this is blah blah" } ] } } ## Genome Map Details [/brapi/v1/maps/{mapDbId}] Status: ACCEPTED Implemented by: Germinate, Cassavabase Used by: Flapjack ### Get map details [GET /brapi/v1/maps/{mapDbId}{?pageSize}{?page}] Provides the number of markers on each linkageGroup and the max position on the linkageGroup + Paramters + mapDbId (required, string, `abc123`) ... the internal db id of a selected map + 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":1000, "currentPage":0, "totalCount":2, "totalPages":1 }, "status" : [], "datafiles": [] }, "result": { "mapDbId": "abc123", "name": "Some map", "type": "Genetic", "unit": "cM", "linkageGroups": ["DEPRECATED - Replaced by 'data' in v1.1"], "data": [ { "linkageGroupName": "1", "markerCount": 100000, "maxPosition": 10000000 }, { "linkageGroupName": "2", "markerCount": 1247, "maxPosition": 12347889 } ] } } ## Genome Map Data [/brapi/v1/maps/{mapDbId}/positions] Status: ACCEPTED. Implemented by: Germinate, Cassavabase Used by: Flapjack ### Get map data [GET /brapi/v1/maps/{mapDbId}/positions{?linkageGroupName}{?pageSize}{?page}] markers ordered by linkageGroup and position + Parameters + mapDbId (required, string, `6`) ... unique id of the map + linkageGroupId (optional, string, `123`) ... **Deprecated** Use linkageGroupName instead + linkageGroupName (optional, string, `1A`) ... The chromosome identifier or the generic linkage group identifier if the chromosome is not applicable. + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data" : [ { "markerDbId": "1", "markerName": "marker1", "location": "1000", "linkageGroupName": "1A" }, { "markerDbId": "2", "markerName": "marker2", "location": "1001", "linkageGroupName": "1A" } ] } } ## Genome Map Data by range on linkageGroup [/brapi/v1/maps/{mapDbId}/positions/{linkageGroupName}] ### Get map data by range on linkageGroup [GET /brapi/v1/maps/{mapDbId}/positions/{linkageGroupName}{?min}{?max}{?pageSize}{?page}] markers ordered by linkageGroup and position + Parameters + mapDbId (required, string, `6`) ... unique id of the map + linkageGroupId (optional, string, `123`) ... **Deprecated** Use linkageGroupName instead + linkageGroupName (required, string, `1A`) ... The chromosome identifier or the generic linkage group identifier if the chromosome is not applicable. + min (optional, integer, `0`) ... minimum position on linkage group + max (optional, integer, `2000`) ... maximum 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data" : [ { "markerDbId": "1", "markerName": "marker1", "location": "1000" }, { "markerDbId": "2", "markerName": "marker2", "location": "1001" } ] } } # Group Locations Location calls. ## List Locations [/brapi/v1/locations] Implemented by: Germinate Get a list of locations. * The `countryCode` is as per [ISO_3166-1_alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) spec. * `altitude` is in meters. **Note**: Consider revising to describe polygon lat/lan points and check if adopting http://geojson.org/ is worth doing for v1. | Variable | Datatype | Description | Required | | ----------------------- | --------------- | ------------------------------------------------------- | :------: | | locationDbId | string | string identifier | Y | | locationType | string | string | Y | | name | string | string | Y | | abreviation | string | string | | | countryCode | string | ISO_3166-1_alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) spec | | | countryName | string | string | | | latitude | string | string | | | longitude | string | string | | | altitude | string | string | | | instituteName | string | string each institute/laboratory can have several experimental field | | | **Deprecated** instituteAdress | string | **Use instituteAddress** | | | instituteAddress | string | string | | | additionalInfo | object | Additional arbitrary info on the study, like objectives or publications | | ### List locations [GET /brapi/v1/locations{?locationType}{?pageSize}{?page}] + Parameters + locationType (optional, string, `Breeding Location`) ... Filter by location type specified. + 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": 0, "pageSize": 1000, "totalCount": 2, "totalPages": 1 }, "status" : [], "datafiles": [] }, "result": { "data" : [ { "locationDbId": "abc123", "locationType" : "Breeding Location", "name": "Ibadan", "abbreviation": "IB", "countryCode": "NGA", "countryName": "Nigeria", "latitude": -21.5, "longitude": 165.5, "altitude": 12, "instituteName": "INRA - GDEC", "instituteAddress": "route foo, Clermont Ferrand, France", "additionalInfo": { "annualMeanRain" : "value", "soilDescription" :"23" } }, { "locationDbId": "def456", "locationType" : "Storage Location", "name": "Goa", "abbreviation": "GO", "countryCode": "IND", "countryName": "India", "latitude": 28.36, "longitude": 77.12, "altitude": 10, "additionalInfo": { "name1" : "value1", "name2" : "value2" } } ] } } ## Location Details [/brapi/v1/locations/{locationDbId}] Implemented by: GnpIS Get details for a location. * The `countryCode` is as per [ISO_3166-1_alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) spec. * `altitude` is in meters. ### Retrieve locations details [GET /brapi/v1/locations/{locationDbId}] + Parameters + locationDbId (required, string, `abc123`) ... the internal DB id for a location + Response 200 (application/json) { "metadata": { "pagination": { "totalCount": 0, "pageSize": 0, "totalPages": 0, "currentPage": 0 }, "status" : [], "datafiles": [] }, "result": { { "locationDbId": "abc123", "locationType" : "Breeding Location", "name": "Ibadan", "abreviation": "IB", "countryCode": "NGA", "countryName": "Nigeria", "latitude": -21.5, "longitude": 165.5, "altitude": 12, "instituteName": "INRA - GDEC", "instituteAddress": "road foo, nigeria", "additionalInfo": { "annualMeanRain" : "value", "soilDescription" :"23" } } } } # Group Samples API methods for tracking/managing plant samples and related meta-data. A 'Sample' in the context of BrAPI, is defined as the actual biological plant material collected from the field. ### Add a sample [PUT /brapi/v1/samples] Call to register the event of a sample being taken. Sample ID is assigned as a result of the operation and returned in response. + Request (application/json) { "sampleDbId": "", "observationUnitDbId": "abc123", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf", } + Response 200 { "metadata": null, "result": { "sampleDbId" : "Unique-Plant-SampleID" } } ## Get a Sample [/brapi/v1/samples/{sampleDbId}] Used to retrieve the details of a single Sample from a Sample Tracking system. ### Get Sample [GET /brapi/v1/samples/{sampleDbId}] + Parameters + sampleDbId (required, string, `Unique-Plant-SampleID`) ... the internal DB id for a sample + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":0, "currentPage":0, "totalCount":0, "totalPages":0 }, "status" : [], "datafiles": [] }, "result": { "sampleDbId": "Unique-Plant-SampleID", "observationUnitDbId": "abc123", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf", } } ## Sample Search [/brapi/v1/samples-search] Used to retrieve list of Samples from a Sample Tracking system based on some search criteria. ### Get Sample Search [GET /brapi/v1/samples-search{?sampleDbId}{?observationUnitDbId}{?plateDbId}{?germplasmDbId}] + Parameters + sampleDbId (optional, string, `Unique-Plant-SampleID-1`) ... the internal DB id for a sample + observationUnitDbId (optional, string, `abc123`) ... the internal DB id for an observation unit where a sample was taken from + plateDbId (optional, string, `PlateID-123`) ... the internal DB id for a plate of samples + germplasmDbId (optional, string, `def456`) ... the internal DB id for a germplasm + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":1000, "currentPage":0, "totalCount":2, "totalPages":1 }, "status" : [], "datafiles": [] }, "result": { "data": [ { "sampleDbId": "Unique-Plant-SampleID-1", "observationUnitDbId": "abc123", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf" },{ "sampleDbId": "Unique-Plant-SampleID-2", "observationUnitDbId": "a1b2c3", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf" } ] } } ### Post Sample Search [POST /brapi/v1/samples-search] + Request { "sampleDbId": ["Unique-Plant-SampleID-1", "Unique-Plant-SampleID-2"], "observationUnitDbId": ["abc123", "a1b2c3"], "plateDbId": ["PlateID-123"], "germplasmDbId": ["def456"] } + Response 200 (application/json) { "metadata": { "pagination" : { "pageSize":1000, "currentPage":0, "totalCount":2, "totalPages":1 }, "status" : [], "datafiles": [] }, "result": { "data": [ { "sampleDbId": "Unique-Plant-SampleID-1", "observationUnitDbId": "abc123", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf" },{ "sampleDbId": "Unique-Plant-SampleID-2", "observationUnitDbId": "a1b2c3", "germplasmDbId": "def456", "studyDbId": "StudyId-123", "plotDbId": "PlotId-123", "plantDbId" : "PlantID-123", "plateDbId": "PlateID-123", "plateIndex": 0, "takenBy": "Mr. Technician", "sampleTimestamp": "2016-07-27T14:43:22+0100", "sampleType" : "TypeOfSample", "tissueType" : "TypeOfTissue", "notes": "Cut from infected leaf" } ] } } # Group Vendor Samples This interface is specific to facilities that performs an external analysis, such as genotyping facilities. The interface should be implemented by that facility's server. The breeding database is the client of this interface. Note that to use these calls, you likely have to use the authentication call prior to connecting (see Authentication section). ## Plate Details by vendorPlateId [/brapi/v1/vendor/plate/{vendorPlateDbId}] Scope: Genotyping facilty. Response data types |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|Object|Object containing MCPD data|Y| |vendorProjectDbId|string|the name or identifier given to a project by the vendor|Y| |vendorPlateDbId|string|the name or identifier of the plate, given by the vendor|Y| |clientPlateDbId|string|the name of the plate, given by the client|Y| |barcode|string|a string that can be represented as a barcode, identifying this plate|N| |plateFormat|string|defines that plate format, usually Plate_96 or tubes for plateless format|Y| |sampleType|string|DNA or RNA or Tissue, etc.|Y| |status|string|The status of the plate in the processing pipeline. Typically, "Received", "Processing", "QC_passed", QC_failed", "Completed" (as per vendor-requirements call)|Y| |samples|Array|list of samples in the plate|Y| ### Plate Details by vendorPlateId [GET /brapi/v1/vendor/plate/{vendorPlateDbId}] + Parameters + vendorPlateDbId (required, string, `8338`) ... The plate ID defined by the vendor + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [] }, "result": { "vendorProjectDbId": "abc123", "vendorPlateDbId": "8338", "clientPlateDbId": "def456", "vendorBarcode": "", "vendorBarcodeImageURL": "", "plateFormat": "Plate_96", "sampleType": "DNA", "status": "(not null)", "statusTimeStamp": "2017-06-01 01:57 GMT", "samples": [ { "sampleDbId": "sample_name", "well": "(optional)", "row": "(optional)", "column": "(optional)", "concentration": "(ng/ul)", "volume": "(ul)", "tissueType": "", "taxonId": { "sourceName": "ncbiTaxon", "taxonId": "http://purl.obolibrary.org/obo/NCBITaxon_4641" } } ] } } ## Register plates [/brapi/v1/vendor/plates] |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|Object containing MCPD data|Y| ### Register plates [POST /brapi/v1/vendor/plates] Note: if the samples array is empty, plate ID will be returned. Samples can be updated later. + Request (application/json) { "plates": [ { "vendorProjectDbId": "project_x", "clientPlateDbId": "required", "plateFormat": "Plate_96", "sampleType": "DNA", "samples": [ { "sampleDbId": "sample_name", "well": "(optional)", "row": "(optional)", "column": "(optional)", "concentration": "(ng/ul)", "volume": "(ul)", "tissueType": "", "taxonId": { "sourceName": "ncbiTaxon", "taxonId": "http://purl.obolibrary.org/obo/NCBITaxon_4641" } } ] } ] } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 }, "status": [], "datafiles": [] }, "result": { "plates": [ { "vendorProjectDbId": "project_x", "vendorPlateDbId": "(not null)", "clientPlateDbId": "(not null)", "vendorBarcode": "(optional)", "vendorBarcodeImageURL": "(optional)", "plateFormat": "Plate_96", "sampleType": "DNA", "status": "", "samples": [ { "sampleDbId": "sample_name", "well": "(optional)", "row": "(optional)", "column": "(optional)", "concentration": "(ng/ul)", "volume": "(ul)", "tissueType": "", "taxonId": { "sourceName": "ncbiTaxon", "taxonId": "http://purl.obolibrary.org/obo/NCBITaxon_4641" }, } ] } ] } } ## Search for plates [/brapi/v1/vendor/plate-search] Search for plates in the database. |Variable|Datatype|Description|Required| |------|------|------|:-----:| |metadata|object|pagination, status|Y| |pagination|object|pageSize, currentPage, totalCount, totalPages|Y| |status|list|code, message|Y| |result|object|Object containing MCPD data|Y| |plates|list|list of plates| |vendorProjectDbIdg||Y| |vendorPlateIdentifier|string||Y| |clientPlateIdentifier|string||Y| |barcode|string||Y| |plateFormat|string||Y| |sampleType|string||Y| |status|string||Y| |samples|Object||Y| |files|Object||Y| |filename|string||Y| |url|string||Y| |md5sum|string||Y| |filetype|string||Y| |clientSampleIdentifiers|list||Y| ### Search for plates [GET /brapi/v1/vendor/plate-search{?vendorProjectDbId}{?vendorPlateDbId}{?clientPlateDbId}{?sampleInfo}{?pageSize}{?page}] + Parameters + vendorProjectDbId (optional, string, `8338`) + vendorPlateDbId (optional, string, `8338`) + clientPlateDbId (optional, string, `8338`) + sampleInfo (optional, boolean, `false`) + 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": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data": [ { "vendorProjectDbId": "abc123", "vendorPlateDbId": "def456", "clientPlateDbId": "ghi789", "vendorBarcode": "", "vendorBarcodeImageURL": "", "plateFormat": "Plate_96"|"tubes", "sampleType": "DNA"|"RNA"|"Tissue", "status": "(not null)", "statusTimestamp": "2017-06-14 04:02:22 PST", "samples": [], "files": [ { "filename": "analysis_results_1", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } }, { "filename": "analysis_results_2", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } } ] }, { "vendorProjectDbId": "abc123", "vendorPlateDbId": "def456", "clientPlateDbId": "ghi789", "vendorBarcode": "", "vendorBarcodeImageURL": "", "plateFormat": "Plate_96"|"tubes", "sampleType": "DNA"|"RNA"|"Tissue", "status": "(not null)", "statusTimestamp": "2017-06-14 04:02:22 PST", "samples": [], "files": [ { "filename": "analysis_results_1", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } }, { "filename": "analysis_results_2", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } } ] } ] } } ### Search for plates [POST /brapi/v1/vendor/plate-search] + Request (application/json) { "vendorProjectDbIds" : ["abc123"], "vendorPlateDbIds" : ["def456"], "clientPlateDbIds" : ["ghi789"], "sampleInfo": "false", "page": 0, "pageSize": 1000 } + Response 200 (application/json) { "metadata": { "pagination": { "pageSize": 1000, "currentPage": 0, "totalCount": 2, "totalPages": 1 }, "status": [], "datafiles": [] }, "result": { "data": [ { "vendorProjectDbId": "abc123", "vendorPlateDbId": "def456", "clientPlateDbId": "ghi789", "vendorBarcode": "", "vendorBarcodeImageURL": "", "plateFormat": "Plate_96"|"tubes", "sampleType": "DNA"|"RNA"|"Tissue", "status": "(not null)", "statusTimestamp": "2017-06-14 04:02:22 PST", "samples": [], "files": [ { "filename": "analysis_results_1", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } }, { "filename": "analysis_results_2", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } } ] }, { "vendorProjectDbId": "abc123", "vendorPlateDbId": "def456", "clientPlateDbId": "ghi789", "vendorBarcode": "", "vendorBarcodeImageURL": "", "plateFormat": "Plate_96"|"tubes", "sampleType": "DNA"|"RNA"|"Tissue", "status": "(not null)", "statusTimestamp": "2017-06-14 04:02:22 PST", "samples": [], "files": [ { "filename": "analysis_results_1", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } }, { "filename": "analysis_results_2", "URL": "", "md5sum": "", "fileType": "fastq", "sampleDbIds": [], "additionalInfo": { } } ] } ] } } ## Vendor specification [/brapi/v1/vendor/specifications] Defines the plate format specification for the vendor. ### Vendor specification [GET /brapi/v1/vendor/specifications] + Response 200 (application/json) { "metadata": { "status": [], "datafiles": [], "pagination": { "pageSize": 0, "currentPage": 0, "totalCount": 0, "totalPages": 0 } }, "result": { "vendorName": "Gene Sequencing Vendor", "vendorDescription": "Gene Sequencing Vendor", "vendorURL": "www.example.org", "contactName": "John Doe", "vendorEmail": "jdoe@example.org", "vendorPhone": "1-234-567-8910", "vendorAddress": "123 Lane St", "vendorCity": "Metropolis", "vendorCountry": "USA", "additionalInfo": { }, "platforms": [ { "platformName": "GBS", "platformDescription": "", "platformURL": "", "contactName": "", "contactEmail": "", "contactPhone": "", "shippingAddress": "", "deliverables": [ { "name": "", "description": "", "format": "" } ], "standardRequirements": { "minConcentration": "", "maxConcentration": "", "minVolume": "", "maxVolume": "", "minSampleNumber": "", "sampleTypes": [ "", "" ], "sampleTypeDetails": "https://...", "inputFormats": [ "Plate_96", "Tubes" ], "inputFormatDetails": "https://...", "plateOrientation": "rowFirst|columnFirst", "blankWellPosition": { "positions": [ "random", "A01", "H12" ], "numberOfBlanksPerPlate": "" } }, "specificRequirements": { }, "statuses": [ { "statusName": "received", "statusDescription": "Platesarereceivedbyvendor." }, { "statusName": "completed", "statusDescription": "Resultfilesareready." }, { "statusName": "rejected", "statusDescription": "Platesarerejectedbyvendor" } ], "taxonomyIdSystem": { "name": "NCBITaxonomyId", "URI": "https://..." }, "tissueIdSystem": { "name": "DArT", "URI": "https://..." } } ] } }