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.