API queries

This page is a consolidated list of user queries for the API to be used in the IE. The list of initial queries is on this page: UserRequirements. I have combined some calls and slightly altered long the lines of the comments.

Core requirements

Query Parameters Returns Comments
Ratings
Get latest rating MP ID Single rating  
Get latest rating and shift MP ID Single shifted rating US only
Get rating periods MP ID, rating group ID Collection of rating periods Rating group ID from earlier call to list param combos.
Get rating table X, Y, Z MP ID, rating IDs Collection of rating tables  
Has the latest rating changed since this date? MP ID, Date Last change date?  
Has the rating period changed since this date? MP ID, Date Last change date?

?PAS - Which rating are we talking about?

PAS - Probably drop? the main req. was fast checking that copy of the lastest rating is still current, so an operational system could scan to see it was using the latest tables.

Have these ratings X, Y, Z changed since this date MP ID, Date Collection of change dates to rating IDs  
List all the paramFrom/To combinations MP ID Collection of paramFrom/To combinations (i.e. rating groups)  
       
Gaugings
Get the latest gauging MP ID Single gauging observation  
Get gauging X, Y, Z MP ID, gauging IDS Collection of gauging observations  
Get gaugings since this date MP ID, date Collection of gauging observations Changed from 'have there been any gaugings since this date?'
Get all From/To combinations MP ID Collection of paramFrom/To combinations  
       
Sections
Get cross-section X, Y, Z MP ID, section ID Collection of cross-sections  
Get cross-section after this date MP ID, date Collection of cross-sections  
Get all cross-section identifers MP ID Collection of cross-sections IDs/references  
       
Range values
Get all range periods MP ID Collection of range periods Return should contain ID/reference to actual range table.
Get range table X, Y MP ID, RT IDs Collection of range tables  

Nice to have

Query Parameters Returns Comments
Ratings
List all ratings MP ID Collection of ratings I feel this should be part of core, with restriction on result size (e.g. via pagination)
       
Gaugings
Get all gaugings MP ID Collection of gauging observations  
List all gaugings with filter MP ID, filters Collection of gauging observations

Filters captures the general filtering use case (e.g. by method, person, range x-y etc)

  • Give me a list of gaugings in period X and stage range Y
  • Give me a list of gaugings not used in conversion X
List gaugings for rating X since date Y MP ID, rating ID, date Collection of gaugings observations Is this the gaugings used in calibration/validation or just if it's used in rating X?
       
Sections
Get all cross-sections MP ID Collection of cross-sections  
Get all cross-sections with filter MP ID, filter Collection of cross-sections

Filter captures number of model-based queries, for example:

  • List of sections, Type X completed in period Y
  • List cross sections completed in period X
Get all types of cross-section available MP ID Collection of cross-section types  
Range values
Get all range tables MP ID Collection of range tables  
Get all changes to range periods after this date MP ID, date Collection of range table periods  
Get all changes to range tables since this date MP ID, date Collection of range tables  
       

Currently out of scope

None.

New requirements (not discussed in meeting)

Monitoring points

  • Get all monitoring points (with paging or some other mechanism to handle large sets)
  • Spatial query (e.g. BBOX) of monitoring points (not likely but worth listing)
  • Describe a phenomenon by identifier

General API principles

From the above requirements, there are some general patterns that fall out:
  1. There must be a base query that can discover the available IDs/references for rating/gaugings/range values/sections at a specific MP.
  2. When requesting full collections of objects, don't encode the objects fully, just return IDs and/or references to them. (I have some reservations about this; the API may become too 'chatty' without a full collection encoding)
  3. Complex filters are not supported in the core API. Some basic ones (such as date time queries) have been promoted to core requirements where necessary. Others may also get 'promoted' as testing progresses.
  4. All queries are done on a specific monitoring point.

-- PeterTaylor - 04 Nov 2013
Topic revision: r3 - 25 Mar 2014, PaulSheahan
This site is powered by FoswikiThe information you supply is used for OGC purposes only. We will never pass your contact details to any third party without your prior consent.
If you enter content here you are agreeing to the OGC privacy policy.

Copyright &© by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding OGC Public Wiki? Send feedback