FlowWorks Web API

Introduction

The FlowWorks WebAPI allows developers to extract and create site, channel and data point information for their sites using a RESTful web service.

The data is formatted in JSON for quick and easy app development across multiple platforms.

Making requests

Requests to the FlowWorks WebAPI use the following basic format:

https://developers.flowworks.com/fwapi/<version#>/<resource>"

Additionally, each request will need to include an Authorization header as the API uses Bearer Authentication.

version#: Refers to the API version you are requesting.
resource: Describes the resource you are requesting. For a complete list of available resources, see the Resources section below.
Bearer Authentication: After obtaining a token from the /tokens resource, include it in the Authorization header of every subsequent request to the API. See the Authentication Workflow next for details. Learn more about Bearer Authentication.

Authentication Workflow

This API uses JWT (JSON Web Tokens) to authenticate and authorize requests to resources.

The authentication workflow for using the API is:

Obtain a JWT Token: POST /tokens

Pass a FlowWorks username and password in the JSON body of the request.
If the credentials are valid, a new JWT token will be returned as a string.
The token will expire after 60 minutes, at which point attempting to use it will result in HTTP 401 Unauthorized responses.
Request a new token once it expires.

Using the JWT Token

Add an 'Authorization' header to every subsequent request and include your token to identify yourself.
The format for this header is: Authorization: Bearer <token goes here...>

Response Objects

Each response contains the following:

ResultCode: A predefined code to represent different exceptions that could happen with the request where 0 represents "OK" and any other value represents different exception codes. This code is generally used for application exceptions. Whenever possible, the api will return also standard http codes.
Result Message: A short description explaining the ResultCode value
Resources: A collection of the requested resource, if the result code was "OK".

Restrictions and limits

There is a rate limit for each API user to prevent an individual from consuming too may resources. If the rate limit is exceeded, no data will be returned and the response message will indicate the problem. If this is happening frequently, please contact support to discuss your requirements, application, and scenario. In some cases, this limit can be increased.

It’s possible to request a set of data that is too large to return in a single response. The maximum size of a response is capped at ~1.5 million data points. Applications should be checking the response message to see if this has occurred, and then make additional requests by varying the date range to complete the set of data.

Resources

Tokens

Retrieve a new JWT token

API	Description
POST tokens	Retrieve a new JWT token, by passing your FlowWorks username and password in the body of the request. See the 'Authentication' section for details on how to use this token in all of your API requests.

Sites

Retrieve information about sites and channels. Retrieve collections of data points from channels. Create sites, channels, and data points.

API	Description
GET sites?siteNameFilter={siteNameFilter}&siteTypeFilter={siteTypeFilter}	Gets a list of sites. With no filter, this will return all available sites. Optionally, the list can be filtered by the site name or site type. The site name filter can partially match multiple sites, or exactly match a single site. For example, "sitenamefilter=ANG" would match sites 'ANG001', 'ANG002', and 'Langford'. The site type filter will match all sites with the type provided. For example, "siteTypeFilter=Sewer" would match all sites whose type is sewer. Both filters can be used invidually or in combination.
GET sites/{id}	Gets the site with the specified site id.
POST sites	Creates a new site based on a site definition passed in the body of the request.
POST sites/{id}/channels	Creates one or more new channels in the identified site.
GET sites/{id}/channels	Get all of the channels from the identified site.
GET sites/{id}/channels/{channelId}	Gets a single channel from the identified site.
GET sites/{id}/channels/{channelId}/data?startDateFilter={startDateFilter}&endDateFilter={endDateFilter}&intervalTypeFilter={intervalTypeFilter}&intervalNumberFilter={intervalNumberFilter}	Get data points from the specified site and channel, which contains numeric or text data. Filter the set of data points by providing a date range. This date range can be specified by providing either: a start and end date OR an interval type and number.
GET sites/{id}/channels/{channelId}/photos?startDateFilter={startDateFilter}&endDateFilter={endDateFilter}&intervalTypeFilter={intervalTypeFilter}&intervalNumberFilter={intervalNumberFilter}	Get data points from the specified site and photo channel, where the values retured are URL's for each photo. Filter the set of data points by providing a date range. This date range can be specified by providing either: a start and end date OR an interval type and number.
GET sites/{id}/data?startDateFilter={startDateFilter}&endDateFilter={endDateFilter}&intervalTypeFilter={intervalTypeFilter}&intervalNumberFilter={intervalNumberFilter}	Get data points from the specified site in every numeric or text channel on the site. Filter the set of data points by providing a date range. This date range can be specified by providing either: a start and end date OR an interval type and number.
POST sites/{id}/data	Create new data points in the specifed site by passing a collection of channels and data points.
POST sites/{id}/channels/{channelId}/data	Create new data points in the specified site and the specified channel, by passing a collection of data points.
POST sites/{siteId}/channels/{channelId}/photo?dataTime={dataTime}	Create a single new photo data point in the specified site and photo channel. The request "Content-Type" should be set to "multipart/form-data" with the file data in the body of the request.

Channels

Retrieve channel information across multiple sites.

API	Description
GET channels/{channelNameFilter}	Gets a list of matching channels across all sites. Channels will be included if they match part or all of the case-insensitive filter. For example, the filter "vel" will match channels like: "Velocity", "Final Level", "Surface VEL", etc.

Units

Retrieve information about units of measurements used in FlowWorks.

API	Description
GET units	Gets a list of all valid units of measurement in FlowWorks.

SiteTypes

Retrieve information about site types used in FlowWorks.

API	Description
GET sitetypes	Gets a list of all valid site types in FlowWorks.

SiteFiles

Retrieve information about files attached to sites visible in FlowWorks mapping. Create and retrieve the attached files.

API	Description
GET sitefiles/{siteId}	Gets the site's attached files list.
GET sitefiles/{siteId}/file/{fileId}	Returns a specific file attached to a site, or an error message
POST sitefiles/{siteName}	Attach files to a site using the site's display name. The request "Content-Type" should be set to "multipart/form-data" with the file data in the body of the request. Overall size of the request cannot exceed 25MB.