API Design

Primary Design Goals

• Provide a friendly user interface (NOTE: users here a generally other machines and developers.)
• Please think about error messages and useful feedback so that scripters/programmers can react to scenarios such as
  • "Feature X is no longer supported."
  • "Unable to parse query because . . . "
  • "Query is legit and everything working great but just no data for that time window."
  • "Something with database/webserver/CWMS Data API (CDA) broke right now - notify the admin."
• Provide metrics to show
  • who has been submitting queries
  • what they asking to see
  • how frequent the queries are
  • which errors happen the most
  • report some of this data to a real-time dashboard of some kind
• Provide data in easy to understand and well defined formats that users can translate into their particular needs
• Provide a denormalized view of data from the CWMS Database
  • E.G. that data returned by CDA does NOT have to match the table structure.
• Allow district personnel to move away from direct database access for custom scripts.
• Be able to run within Tomcat environment provided by the following:
  • T7 installs
  • CPC/DMZ National Infrastructure.
• Prioritize web based applications in data access design
• The default format for all endpoints is moving to JSON from tabulation.
• Not reveal, or push a dependence on, the internal structure of the database
  • This is not for security through obscurity but so that downstream users aren't dependent on internals and thus the internal structure can change as WE need it to.

Secondary Design Goals

• Eventually replace all direct database access for downstream CWMS Components and users
• If the maintenance burden is minimal, provide additional endpoints and formats of data to simplify downstream applications.

Design Philosophy

• Current we are using a mechanism of read-only data transfer objects (DTO) specific to CDA when extracting data out of the database.
  • This allows us to set the appropriate annotations for naming in JSON and XML as well as what grouping we expected for data derived from multiple
• Names for fields should be sensible. Database column names are not always sensible.
  • e.g. in a location DTO, uses of name instead of location_id
• Do not expose surrogate keys. tables.
• Favor JSON, XML, other. In that order.
  • If an already well defined, and easy to use, JSON or XML standard exists, we should use it.
• CDA code is allowed direct read access to tables, views, etc.
  • E.G. using existing data access APIs, while favored, is not a hard requirement if the logic is easier or better with another way.
• While CDA has a version to indicate what release it is, we version data types instead of the API.
  • This versioning happens within the Content-Type and Accept headers
  • Formats determined to be deprecated will be kept 1 year after they are replaced or determined to be not required.
  • New formats can go in immediately, but to avoid too many versions running around will be labelled at "BETA" until a vote is taken among developers that it is final.
• Provide pagination of large amounts of data instead of continuing to hang up systems and interfaces.
• Clients performing parallel queries is favored over trying to group data for single large requests.
  • e.g. we will operate under the assumption that response times over 500-1000ms means something is wrong.