FORMAT: 1A

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. The listserve for discussions and announcements is at http://mail2.sgn.cornell.edu/cgi-bin/mailman/listinfo/plant-breeding-api . Additional documentation is in the Github wiki.

API requests are structured as "<server>/brapi/v1/", where "v1" is the version number of the API, followed by the command.
Example: /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 "<server>" identifier. An arbitrary number of levels can be inserted between the domain name and the crops or brapi level, if needed.

Example: superBreedingServer.org/maize/brapi/v1/markerprofiles/2939

The return objects are encoded in JSON. The response always consists of a "metadata" key that minimally contains the pagination information in a "pagination" key and the status information as well as a "datafiles" key that lists URLs to data files generated by the call.

If the response is a single record that doesn't require pagination, then the value for the "pagination" key is returned with all the keys set to zero. When the results are paginated, the keys "pageSize", "currentPage", "totalCount", "totalPages" contain the appropriate values. Note that pages are zero indexed, so the first page will be page 0 (zero). (For the user interface, this may be adjusted by adding 1).

The status object contains a list of objects with the keys "code" and "message". If no status is reported, the empty list should be returned.

The datafiles key contains a list of strings. The empty list should be returned if no datafiles are present.

The payload data is contained in a key called "result", containing an object with the response. If there is a paginated response, a "data" key will be present, with a list value, which will be paginated over (showing pageSize elements of the currentPage).

Additional documentation is in the GitHub wiki. See especially the [Best Practices and Conventions] (https://github.com/plantbreeding/documentation/wiki/Best-Practices-and-Conventions).

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": {}
    }
  

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:

Given this response, a GET on the resource /allelematrix-search/status/extract_2016-12-15-20-37-015 will give a response as follows:

Scope: "CORE", "PHENOTYPING", "GENOTYPING", "OTHER".
Status: "STABLE", "ACCEPTED", "IN DISCUSSION", "SUGGESTED".