API User Guide

The Fish Kill DB API is organized around REST. This API returns JSON-encoded responses and uses standard HTTP response codes and verbs. Fish Kill DB uses many of these endpoints itself for the retrieval and display of data. The API can be used to programmatically retrieve AQuIA water quality data by other applications.

When you make a request to the REST API, you will specify an HTTP method and any path parameters. Additionally, you might also specify query parameters. The API will return the response status code and usually a response body.

The API reference documentation describes the method, path, and parameters for every operation. It also displays example requests and responses for each operation.

Path Parameters

Path parameters modify the operation path. For example, the Get Events By Origin path is/api/v1/events/by_origin/{cat}. The curly brackets{ }denote a path parameter that needs to be specified. In this example, the origin category (cat) for the site must be provided, where "cat" is one of Natural, Anthropogenic, or Unknown.

Query Parameters

Query parameters are typically optional parameters that may be supplied to control what data is returned for a request. For example, these parameters can limit the number of results returned or change the sort order.

Fields Parameter

All Fish Kill DB endpoints can use the fields parameter. This parameter filters the API response so that the response only includes a specific set of fields. The fields parameter lets you remove nested properties from an API response and thereby reduce bandwidth usage. The following rules explain the supported syntax for the fields parameter value:

• Use a comma-separated list (fields=a,b) to select multiple fields.
• Use an asterisk (fields=*) as a wildcard to identify all fields.
• Use parentheses (fields=a(b,c)) to specify a group of nested properties that will be included in the API response.
• Use a forward slash (fields=a/b) to identify a nested property.

Example:https://programs.iowadnr.gov/fishkill/api/v1/events/?fields=date,cause,magnitude(magnitudeDesc,estFishKilled)will return only the fields for the Date of the Event, the cause, and the magnitude object which will contain only the magnitude description and the estimated number of fish killed.

Responses

The Fish Kill DB API uses conventional HTTP response codes to indicate the success or failure of an API request. Unless otherwise specified, the response body is in JSON format.

200 - OK	Everything worked as expected
400 - Bad Request	The request was unacceptable, often due to a malformed request or missing a required parameter
404 - Not Found	The requested resource doesn't exist
500 or other 5xx - Server Errors	Something went wrong on our end.

Versioning

The Fish Kill DB API uses a url path segment (api/v{version number}/) approach to versioning. When backwards-incompatible changes are made, a new version is created. The following changes are considered to be backwards-compatible:

• Adding new API resources/endpoints
• Adding new optional requets parameters to existing API methods
• Adding new properties to existing API responses
• Adding new enumeration types to existing properties. Your methods should gracefully handle unfamiliar enumerations.

For all API updates, please visit the API Changelog.