ESMIS API Documentation - cul-it/open-esmis GitHub Wiki

ESMIS API Documentation

Table of Contents

• Overview
• Conventions
• API Get Methods
  • Agency Methods
  • Publication Methods
  • Release Methods
• Authentication
• Testing API methods using the Swagger UI
• API Post Methods
  • Publication Create
  • Release Create

Overview

This page documents the ESMIS API (Application Programming Interface). The API provides access to data for Agencies, Publications, and Releases. The API uses rest style http requests to return the data, in JSON format, for use by external systems. For the Publications and Releases API methods, it is split into "read" (GET) methods and "write" (POST) methods. The Agency methods only include "read" methods.

Detailed documentation for all API methods can be found using a page created using the Swagger project. Swagger is a tool for documenting and testing APIs and a page has been created within the ESMIS application. It can be found at http://usda.library.cornell.edu/apidoc/index.html. Further information about the Swagger UI page can be found below.

Conventions

For future reference the following variables/information can be used:

$site_host - The main host name for the ESMIS site (e.g. http://usda.library.cornell.edu)

$apiBase - The base path for the API to be appended to the $site_host (e.g. /api/vi)

$method - The name of an API endpoint. (e.g. /agency/findAll)

Put these together to construct an API request, for example http://usda.library.cornell.edu/api/v1/agency/findAll

Some of the api methods require a parameter. If a method requires a parameter it will be shown with curly braces around it. For example:

http://usda.library.cornell.edu/api/v1/agency/findByAcronym/{acronym}

Replace {acronym} with a valid string to get:

http://usda.library.cornell.edu/api/v1/agency/findByAcronym/nass

API GET Methods

The following is a list of all implemented Methods. These methods will return agency, publication, or release data. API POST (write) methods will be described later.

Agency Methods

• /agency/findAll
• /agency/findByAcronym/{agency_acronym}
• /agency/findById/{agency_id}

Publication Methods

• /publication/findAll
• /publication/findByAgency/{agency_acronym}
• /publication/findById/{id}
• /publication/findByIdentifier/{agency_identifier}
• /publication/search

Release Methods

• /release/findById/{id}
• /release/findByIdentifier/{agency_identifier}
• /release/findByPubId/{publication_id}

Authentication

All web services require authentication. The Authentication method is using JWT (JSON Web Tokens) Authentication. An authentication token may be obtained by making a POST request to the /user_token service in the application. In order to obtain a token an authorized email address and password must be sent with the request. NOTE: At this time, credentials for apiusers have not yet been created. Once they become available, they will be shared with those that will use the API. The following contains an example bash shell script which will make a request for a user token (note the email address and password are not "real"). It used the curl command to make requests to the /user_token services and to the API endpoints.

#!/bin/bash
json=$(curl -s -X POST "http://usda.library.cornell.edu/user_token" -d '{"auth": {"email": "apiuser", "password": "my_password"}}' -H "Content-Type: application/json")
token=$(echo $json | cut -d":" -f2 | sed -e 's/"//g' -e 's/}$//g')
echo "Token: $token"

Once an authentication token is obtained, subsequent calls to the API must include this token. For example, the following bash script obtains a token, then uses the token to call one of the API methods:

#!/bin/bash
apiBase=http://usda.library.cornell.edu/api/v1
json=$(curl -s -X POST "http://usda.library.cornell.edu/user_token" -d '{"auth": {"email": "apiuser", "password": "my_password"}}' -H "Content-Type: application/json")
token=$(echo $json | cut -d":" -f2 | sed -e 's/"//g' -e 's/}$//g')
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -H "Accept: application/json" "$apiBase/agency/findAll"

Testing API methods using the Swagger UI

The API documentation can be found on the Swagger UI page at http://usda.library.cornell.edu/apidoc/index.html

The page lists all of the API methods available, the expecting input and expected output. The API methods are organized into three sections: Agency, Publication, and Release. For each method, it shows the path one needs to append (e.g /agency/findAll) to the $site_host/$apiBase URL. Selecting any API method will expand the view to show detail about the method. It will contain a brief description, any parameters to be passed, and the possible responses.

Parameters

Parameters are either "path" parameters or "query" parameters (and a method can have both types). A path parameter is a string that is part of the full path. For example, as shown earlier:

http://usda.library.cornell.edu/api/v1/agency/findByAcronym/nass

"nass" is a path parameter to pass the acronym of the agency to the /agency/findByAcronym method. "Query" parameters are at the end of the full path and follow a "param=value" convention. The first query parameter in a URL will be preceded by a question mark (?} and all subsequent query parameters are preceded by an ampersand (&). As an example, the /release/findByIdentifier method requires a "path" parameter (an identifier) and two query parameters (start_date, end_date). For example:

http://usda.library.cornell.edu/api/v1/release/findByIdentifier/PoulSlau?start_date=01/01/2017&end_date=12/31/2017

This would return release information for the all releases with an identifier of PoulSlau (Poultry Slaughter) from January 1st, 2017 to December 31, 2017.

Responses

All API methods will return several possible responses. Each response is associated with a standard HTTP Response code. A 200 response indicates a successful response. A 400 error is returned when the request was malformed (for example, if a required parameter was not provided). A 404 error is returned when a request was made, but it could not find the date requested. A 500 error is a "catch all" error that indicates that something went wrong while processing the request.

All responses will return information in JSON format. The Swagger UI will describe an example response for each method for each "type" of response.

Models

At the bottom of the Swagger UI page is a list of "models" that are used for passing data into POST requests and data that is returned as a response (including errors). For each model, the expected field, type of field, and a description of each field is provided.

Try It Out

For each API method the Swagger UI can be used to test the method. Click on the method name to expand it, showing the parameters and responses, then click on the "Try it Out" button. This will show the list of parameters (if any) and a select list or text input form for entering parameters. Enter the require parameters then select the "Execute" button.

This will execute an API request using the curl command (and show the command it executed) and show the actual response.

See Example API Client Scripts for more example "read" scripts.

API POST Methods

API POST (or write) methods differ from GET methods such that a client using the API will "post" some data to the site, rather than just read data. API post methods expect that content sent to the API to be in JSON format. The API implements two POST methods, one for creating a Publication and one for adding a Release to a Publication.

Publication Create

• /publication/create
• Parameters The Publication create methods accepts JSON in the request body as shown below. Some of the fields are optional.

{
  "id" : null,
  "title" : "Poultry Slaughter",
  "description" : "   These reports contain the number of head and live weight of chickens, turkeys, ducks and other poultry slaughtered under Federal inspection. Also included are average live weights, pounds certified, and both ante-mortem and post-mortem condemnations. Data for young chickens and young turkeys are shown for selected states.   ",
  "identifier" : "PoulSlau",
  "status" : "Active",
  "resourceType" : "Report",
  "dateModified" : "12/15/2017 15:12 PM",
  "dateUploaded" : "12/15/2017 15:12 PM",
  "origKeywords" : [ "poultry", "slaughter", "chicken", "turkey", "chickens", "turkeys", "ducks" ],
  "keywords" : [ "poultry", "slaughter", "chickens", "turkeys", "ducks" ],
  "subject" : [ "Animals and Animal Products:Poultry" ],
  "upcomingReleases" : [ "12/26/2017 03:12 AM" ],
  "frequency" : "Monthly",
  "authors" : [ ],
  "issn" : "",
  "contactName" : "",
  "contactOrganization" : "",
  "contactEmail" : "[email protected]",
  "contactPhone" : "202-690-3237",
  "agencyAcronym" : "NASS",
  "subscribable" : "Y"
}

See Example API Client Scripts for more details

Release Create

• /release/create

• Parameters The Release create methods accepts JSON in the request body as shown below. Because creating a release involves uploading one or more files, constructing a client is much more complicated and requires a multipart/form request.

Example JSON for /release/create request

{
  "identifier" : "PoulSlau",
  "title" : "Poultry Slaughter",
  "agency_acronym" : "NASS",
  "description" : "",
  "date_uploaded" : "2018-02-07T14:56:37.268+00:00",
  "date_modified" : "2018-02-07T14:56:37.268+00:00",
  "release_datetime" : "05/25/2017",
  "temporal_coverage" : null,
  "uploaded_files" : [ "/cul/data/usda/nass/PoulSlau/2010s/2017/PoulSlau-05-25-2017.pdf", "/cul/data/usda/nass/PoulSlau/2010s/2017/PoulSlau-05-25-2017.txt", "/cul/data/usda/nass/PoulSlau/2010s/2017/PoulSlau-05-25-2017.zip" ]
}

The files included the uploaded_files element must be included as items in the multi-part request.

See Example API Client Scripts for more details