API User Guide

The AQuIA API is organized around REST. This API returns JSON-encoded responses and uses standard HTTP response codes and verbs. AQuIA 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 Site by ID path is /api/v1/sites/{id}. The curly brackets { } denote a path parameter that needs to be specified. In this example, the unique key (SiteID) for the site must be provided.

Query Parameters

Query parameters are typically optional parameters that may be supplied to control what data is returned for a request. For example, the Get Results by ID path has several different parameters, such as casRN, limit, and order to select results by the analyte's Chemical Abstract Registry Number (casRN), or limit the number of results returned, or change the sort order.

Fields Parameter

All AQuIA 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/aquia/api/v1/results/by_site/10030001?fields=sampleDate,analyte,result,unit,site(siteID,name,type)will return only the fields sampleDate, analyte, result, unit, and the fields siteID, name, and type within the site object.

Responses

The AQuIA 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 missing a required parameter
404 - Not Found	The requested resource doesn't exist
500 or other 5xx - Server Errors	Something went wrong on AQuIA's end.

Versioning

The AQuIA 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 request 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.