BMSAPI Authentication

BMS API is a set of RESTful web services that allow access to data in the BMS database.

All BMS API calls require authentication and valid access token provided.

For API Consumers

Understanding Authentication

BMS API services expose operations on data created by registered BMS users as they carry out breeding programs and studies for various crops. Hence access to the BMS API services require authentication as the same registered user. BMS API uses a light-weight variant of the popular OAuth protocol known as X-Auth. In exchange of valid users credentials (Workbench user name and password) BMS API issues a fixed time window (configurable per deployment) ticket/token which is then required to be provided for each and every BMS API service invocation as part of X-Auth-Token request header (orAuthorization in the case of BrAPI Resources). Example below illustrates the scenario of a command line client (curl) accessing the API:

Request a listing of programs without authentication:

We are using curl to demonstrate the request/response behaviour. Any equivalant HTTP client (e.g. Postman) which allows user to specify HTTP request headers can be used.

Request:

curl http://<host>:<port>/bmsapi/program/list

Response:

Code: 401
Response Body:
{
  "timestamp": 1447884520756,
  "status": 401,
  "error": "Unauthorized",
  "message": "Access Denied"
}

This is because there is no authentication header provided as part of the request.

Request a listing of programs with authentication:

First, authenticate with credentials of a registered Workbench user:

Request :

curl -X POST -H "Content-Type: multipart/form-data;" -F "username=naymesh" -F "password=naymeshspassword" 'http://<host>:<port>/bmsapi/authenticate'

Response (if credentials are correct):

Code: 200
Response Body:
{
  "token": "naymesh:1447886088052:fdd12b1069a9f28ddee2f8d42d30dde5",
  "expires": 1447886088052
}

Now make the program listing API request with the authentication header using the token provided in response to successful authentication as in example above:

Request:

curl -X GET -H "X-Auth-Token: naymesh:1447886088052:fdd12b1069a9f28ddee2f8d42d30dde5" 'http://<host>:<port>/bmsapi/program/list'

Response:

Code: 200
Response Body:
[
    {
        "id": "1",
        "uniqueID": "fb0783d2-dc82-4db6-a36e-7554d3740092",
        "name": "Naymesh's Program",
        "createdBy": "naymesh",
        "members": [
            "naymesh"
        ],
        "crop": "maize",
        "startDate": "2015-11-11"
    },
    {
        "id": "2",
        "uniqueID": "57b8f271-56db-448e-ad8d-528ac4d80f04",
        "name": "Akhil's Program",
        "createdBy": "akhil",
        "members": [
            "akhil",
            "naymesh"
        ],
        "crop": "maize",
        "startDate": "2015-12-12"
    }
]

BrAPI Compliant Authentication

BMSAPI also supports BrAPI Compliant Authentication for its BrAPI resources (/bmsapi/brapi/).

Authenticate with credentials of a registered Workbench user:

Request :

curl \
'http://<host>:<port>/bmsapi/brapi/v1/token' \
-H 'Content-Type: application/json' \
-d @- << EOF
{
    "username": "naymesh",
    "password": "naymeshpassword",
    "grant_type": "password",
    "client_id": ""
}
EOF

or

curl \
'http://<host>:<port>/bmsapi/brapi/v1/token' \
-H 'Content-Type: application/json' \
-d $'{ "username": "naymesh",  "password": "naymeshpassword",  "grant_type": "password",  "client_id": ""}'

Response (if credentials are correct):

Code: 200
Response Body:
{
  "metadata": {
    "pagination": null,
    "status": null,
    "datafiles": []
  },
  "userDisplayName": "naymesh",
  "access_token": "naymesh:1484079802532:bfe0f2886a18c6e8dea0e8e0be2292bc",
  "expires_in": 1484079802532
}

Now make the request to a BrAPI service with the authentication header using the token provided in response to successful authentication as in example above:

Request:

curl -X GET -H "Authorization: Bearer naymesh:1484079802532:bfe0f2886a18c6e8dea0e8e0be2292bc" 'http://<host>:<port>/bmsapi/wheat/brapi/v1/locations'

Response:

Code: 200
Response Body:
{
  "metadata": {
    "pagination": {
      "pageNumber": 1,
      "pageSize": 100,
      "totalCount": 5086,
      "totalPages": 51
    },
    "status": null,
    "datafiles": null
  },
  "result": {
    "data": [
      {
        "locationDbId": 1,
        "locationType": "COUNTRY",
        "name": "Afghanistan",
        "abbreviation": "AFG",
        "countryCode": "AFG",
        "countryName": "Afghanistan",
        "latitude": 33,
        "longitude": 65,
        "attributes": []
      }
	  // etc
    ]
  }
}

Authorization

Based on the details of the user making requests to BMSAPI, the data returned is restricted and filtered in the same way as the data is filtered/restricted when user interacts with the same data via the BMS application user interface. For example, users only see the data for the programs/studies they have created or the programs/studies that they are part of. As shown in example above, the listing returned two programs one which the authenticated user (naymesh) has created and one where the user is a member.