Migrating Apps and Scripts from v1 to v2
HydroServer v2 changes the Data Management API, the Python and TypeScript clients, and how apps sign users in. This guide lists what changed for scripts, apps, dataloggers, and other tools that use HydroServer's APIs or client libraries, and what you need to update. Each section links to the page that describes the v2 behavior in full.
If you only use HydroServer through the Data Management App in your browser, you don't need to change anything. Your data is migrated when your HydroServer administrator upgrades the instance.
What Keeps Working
- API keys: keys created in v1 keep working. Each one is now a service account with the same key and the same access to its workspace.
- SensorThings API: reading data and posting observations work as before, with the property changes listed in SensorThings API.
- IDs: workspaces, monitoring sites (Things in v1), datastreams, observations, methods (Sensors in v1), observed properties, units, processing levels, and result qualifiers keep their IDs. File attachments and controlled vocabulary terms get new IDs.
What to Upgrade
| Tool | Upgrade to | Details |
|---|---|---|
| hydroserverpy | 2.x: pip install "hydroserverpy>=2.0,<3" | hydroserverpy |
hydroserver-ts (@hydroserver/client) | 2.x: npm install @hydroserver/client@^2 | hydroserver-ts |
| Streaming Data Loader | The latest release | Streaming Data Loader |
Authentication
- API keys: send them in the
X-Api-Keyheader, as before. Keys now belong to service accounts, which you manage under the workspace. See Service Accounts and API Keys. - Email and password: HTTP Basic authentication works as before. The v1 sign-in API at
/api/auth/{client}/session, and theAuthorization: Bearersession tokens it returned, are removed. Scripts that used them should send email and password with HTTP Basic, or preferably switch to a service account's API key. - Apps that sign users in: the rest of the v1 account API under
/api/auth/, including sign-up, password reset, email verification, and third-party provider connections, is also removed. Apps now sign users in with OpenID Connect (OIDC), sendAuthorization: Bearer <access token>, and send users to HydroServer's account pages to sign up or edit their account. Your HydroServer administrator must register each app as an OIDC client.
See Authenticating and Using OIDC Scopes.
Data Management API
The Data Management API moved from /api/data to /api/ogc and now implements OGC API - Features. Each type of resource is a collection, with its items at /api/ogc/collections/{collectionId}/items. See Using the Data Management API for how to use it.
Paths
All v1 paths below are under /api/data, and all v2 paths are under /api/ogc/collections. Paths under an item, such as a task's runs and trigger endpoints, follow the same pattern: /etl/tasks/{id}/runs becomes /etl-tasks/items/{id}/runs.
| v1 path | v2 path |
|---|---|
/workspaces | /workspaces/items |
/workspaces/{id}/collaborators, /workspaces/{id}/transfer | /workspaces/items/{id}/collaborators, /workspaces/items/{id}/transfer |
/workspaces/{id}/api-keys | /workspaces/items/{id}/service-accounts |
/roles | /roles/items |
/things | /monitoring-sites/items |
/datastreams | /datastreams/items |
/things/{id}/tags, /datastreams/{id}/tags | The item's tags field, changed with PATCH |
/things/{id}/file-attachments, /datastreams/{id}/file-attachments | /monitoring-sites/items/{id}/linked-resources, /datastreams/items/{id}/linked-resources |
/datastreams/{id}/observations | /observations/items?datastreamId={id} |
/datastreams/{id}/observations/bulk-create, .../bulk-delete | /observations/bulk-create, /observations/bulk-delete, with datastreamId in the request body |
/sensors | /methods/items |
/observed-properties, /units, /processing-levels, /result-qualifiers | /observed-properties/items, /units/items, /processing-levels/items, /result-qualifiers/items |
/things/site-types, /sensors/method-types, /units/types, /observed-properties/variable-types | /monitoring-site-types/items, /method-types/items, /unit-types/items, /observed-property-types/items |
/datastreams/statuses, /datastreams/sampled-mediums, /datastreams/aggregation-statistics | /datastream-statuses/items, /sampled-mediums/items, /aggregation-statistics/items |
/things/file-attachment-types, /datastreams/file-attachment-types | /linked-resource-types/items |
/things/sampling-feature-types, /sensors/encoding-types | Removed |
/etl/data-connections, /etl/tasks | /etl-data-connections/items, /etl-tasks/items |
An ETL task's mappings | /etl-mappings/items, filtered by etlTaskId |
/products/rating-curves, /products/tasks | /data-product-rating-curves/items, /data-product-tasks/items |
/products/tasks/{id}/transformations/{type} | /data-product-transformations/items, with taskId and transformationType |
/monitoring/tasks | /monitoring-tasks/items |
/monitoring/tasks/{id}/rules | /monitoring-rules/items, with taskId |
/quality-control/histories | /quality-control-histories/items |
Controlled vocabularies are now collections of items with a name and description, rather than lists of strings.
Requests and Responses
- Query parameters use camelCase, such as
monitoringSiteIdinstead ofthing_id, and the API rejects parameters it doesn't recognize with400. See Filtering. - Paging uses
limitandoffsetinstead ofpageandpage_size. Lists are returned in adataarray with the total count inmeta.numberMatchedand page links inlinks, instead of a bare array withX-Total-CountandX-Total-Pagesheaders. See Paging. - Single items are returned in
data, instead of as the bare object. - Sorting uses
sortbyinstead oforder_by. See Sorting. - Related records: use
includeinstead ofexpand_related. Related records are returned once each inincluded, instead of nested in each item. See Including Related Records. - Time filters: use
datetimeinstead of the*_minand*_maxtime parameters, such asphenomenon_time_minandphenomenon_time_maxon observations. See Filtering by Time. - Observation formats: use the
profileparameter with the row or column profile instead offormat=roworformat=column. See Compact Observation Responses. - Creating an item returns
201with only the new item'sid, instead of the full item. - Updating uses JSON Merge Patch.
nullclears an optional field, and objects such astagsare merged key by key. See Updating. - Errors return their explanation in
messageinstead ofdetail. See Errors.
Fields
The main renamed and restructured fields are listed below. See the Data Dictionary for every field in v2.
| Resource | v1 | v2 |
|---|---|---|
| Monitoring sites (Things) | samplingFeatureCode, siteType | code, type |
samplingFeatureType | Removed | |
location object | latitude, longitude, elevationM, elevationDatum, adminArea1, adminArea2, and country on the site | |
fileAttachments | linkedResources | |
| Monitoring sites and datastreams | tags as a list of key and value objects | tags as an object of keys and values |
| Datastreams, data product tasks, monitoring tasks, rating curves | thingId | monitoringSiteId |
| Datastreams | sensorId, fileAttachments | methodId, linkedResources |
observationType, resultType | type (optional, defaults to timeSeriesCoverage). See Datastream types. | |
isVisible | isRestricted, with the opposite value. See Restricted Data Download. | |
| Methods (Sensors) | methodCode, methodType, methodLink | code, type, definition |
manufacturer, model, modelLink | sensorModelManufacturer, sensorModel, sensorModelDefinition | |
encodingType | Removed | |
| Processing levels | code, definition, explanation | code, name, definition (a URL), description |
| Result qualifiers | code | name |
| Observations | resultQualifierCodes | resultQualifiers |
| Workspaces | owner, pendingTransferTo, collaboratorRole | ownerEmail, pendingTransferToEmail, collaboratorRoleId |
| Service accounts (API keys) | expiresAt, lastUsed | keyExpiresAt, lastUsedAt |
roleId | Set when creating the account. Change it afterwards through the workspace's collaborators. | |
| Data product transformations | inputDatastream | inputDatastreams |
Datastream Types
A datastream's free-text observationType and resultType are replaced by type, whose allowed values are defined by HydroServer. v2.0 has one type, timeSeriesCoverage, and every migrated datastream has it. The v1 values aren't kept unless your administrator saved them as tags before upgrading. See Datastream observation and result types are replaced.
- Stop sending
observationTypeandresultTypewhen you create or update a datastream. Sendtype, or leave it out to gettimeSeriesCoverage. Any othertypevalue returns400. - Read
typeinstead ofresultTypefrom datastream responses. - Filter and sort with
typeinstead ofobservationTypeandresultType, such as?type=timeSeriesCoverageandsortby=type. - Datastream CSV downloads have a
# Type:header line instead of# ObservationType:and# ResultType:.
Restricted Data Download
A datastream's isVisible is replaced by isRestricted, which has the opposite value: a datastream that had isVisible: false now has isRestricted: true. In v1, isVisible only hid observations in the Data Management Web Application. In v2, isRestricted restricts data download and query in every API: the datastream and its metadata, including valueCount, phenomenonBeginTime, and phenomenonEndTime, stay public, but its observations are only returned to the workspace owner and collaborators whose role can view observations. isRestricted and isPrivate are independent, and changing one never changes the other.
- Send and read
isRestrictedinstead ofisVisible, and sort withsortby=isRestricted. - If a datastream's data download is restricted and you can't access its data, observation requests return none of its observations and their
numberMatcheddoesn't count them. This includes the SensorThings API and CSV downloads.
SensorThings API
The SensorThings API's paths and query options haven't changed, but its entities now come from v2's data model. See Retrieving Data with the SensorThings API.
- Things: in each Thing's
properties,samplingFeatureCodeandsiteTypeare nowcodeandtype,samplingFeatureTypeis removed, andfileAttachmentsis nowlinkedResources. - Locations: each monitoring site's Location now has the same ID, name, and description as the site, so update anything that stored v1 Location IDs.
- Sensors: each Sensor is a method. Its
encodingTypeis alwaysapplication/json, and itsmetadatakeeps the same keys as v1. - Datastreams: in each Datastream's
properties,fileAttachmentsis nowlinkedResources,resultTypeis nowtype,isVisibleis nowisRestricted(see Restricted Data Download), andprocessingLevelCodecan benull. An ObservedProperty'svariableCodecan also benull. - Observation type: every Datastream's
observationTypeishttp://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement, and$filteronobservationTypecompares against that value.
hydroserverpy
Install hydroserverpy 2.x, which works with HydroServer v2. See the Python Client Reference for every class and method.
Connecting: create the client with
apikey,emailandpassword, or the newaccess_tokenoption. Theauth_routeparameter and thelogin()andlogout()methods are removed, andbase_routenow defaults to/api/ogc. See Connection.Paging:
list()methods takeoffset,limit, andsortbyinstead ofpage,page_size, andorder_by, and collections have matching attributes in place ofpage,page_size, andtotal_pages. See Common list() parameters.Renamed services and models:
v1 v2 hs.things,Thinghs.monitoring_sites,MonitoringSitehs.sensors,Sensorhs.methods,MethodAPI keys ( workspace.apikeys,create_api_key(), ...)Service accounts ( workspace.serviceaccounts,create_service_account(), ...)The mappingsargument ofhs.etltasks.create()andupdate()hs.etlmappings.task.mappingsstill lists a task's mappings.thing,thing_id,sensor,sensor_idarguments and attributesmonitoring_site,monitoring_site_id,method,method_idRenamed fields: model attributes follow the API's field changes, in snake_case. For example,
site_typeis nowtype,observed_property_typeandunit_typeare nowtype, and a result qualifier'scodeis nowname.Datastream types: remove the
observation_typeandresult_typearguments fromhs.datastreams.create(),update(), andlist(). Usetypeinstead, whichcreate()sets totimeSeriesCoverageby default. See Datastream Types.Tags and files:
add_tag()andupdate_tag()are replaced byset_tag(), anddelete_tag()takes only the key. File attachment methods are replaced by linked resource methods such asadd_linked_resource(). See Tags and Linked resources.Transformations and rules: data product transformation and monitoring rule methods no longer take a
task_idwhen you get, update, or delete one by its ID. See Data Product Transformations and Monitoring Rules.Observations:
get_observations()takesresult_qualifiersinstead ofresult_qualifier_code, andload_observations()addsphenomenon_time_startandphenomenon_time_endforreplacemode.
hydroserver-ts
Install @hydroserver/client 2.x, which works with HydroServer v2. See Using the TypeScript Client for every service.
- Signing in:
hs.session.login(email, password)is replaced byhs.session.login(returnTo), which opens HydroServer's sign-in page. Use theoidcoption to sign users in with OIDC, oraccessTokenProviderif your app already has access tokens. Account features that used the v1 account API, such as password reset and email verification, now happen on HydroServer's account pages. See Authentication and session. - Renamed services:
hs.thingsis nowhs.monitoringSites,hs.sensorsis nowhs.methods, andhs.thingFileAttachmentsis replaced by linked resource methods onhs.monitoringSitesandhs.datastreams. New services cover ETL mappings, monitoring rules, data product transformations, and each controlled vocabulary. - Query parameters:
list()takesoffset,limit, andsortbyinstead ofpage,page_size, andorder_by, and filters use camelCase, such asisAssociatedinstead ofis_associated. See Collections and CRUD helpers. - Models: model fields follow the API's field changes.
Streaming Data Loader
Update the Streaming Data Loader to its latest release, which works with HydroServer v2. See Using the Streaming Data Loader.
