API User Guide

The ADBNet API is organized around REST. This API returns JSON-encodedresponses and uses standard HTTP response codes and verbs. ADBNet uses many of these endpoints itself for the retrieval and display of data. The API can be used to programmatically retrieve ADBNet water quality assessment 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.

Fields Parameter

All ADBNet 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/adbnet/api/v1/segments/16?fields=segid,name,wbtypewill return only the fields SegID, Name, and WBType.

Responses

The ADBNet 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.

Versioning

The ADBNet 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.