NB: Vesion 2 of this API has been released. Please upgrade to that. Version 1 will be discontinued on may 1, 2020.
This documentation only covers version 2.

REST API

This service is a typical REST API and it uses HTTP as communication protocol. It is only designed for retrieval of data so you should only use requests with the HTTP verb GET . It is important that the clients respect the HTTP status codes, and only use data returned in combination with the HTTP status code 200. The service supports the header Accept-Encoding: gzip, deflate . Use it if your client handles gzipped content to decrease download time.

The service uses a handful of formats for the service protocol. Clients may use any one of these formats and can switch between formats at any time. To specify which one to use, a suffix is appended to the URL. Note that all formats are not available for all resources. See Mediatypes for more information.

Typical requests and responses

...
...

...
...

...
...

...
...

Mediatypes

The API is based on four primary mediatypes. There may also be references to other mediatypes (i.e. for metadata) but these are not included in this documentation.

For all resources except Data a client can use ATOM , XML or JSON . If no suffix is specified then ATOM is used as the default mediatype.

All Data are available as ZIP . ZIP is the only mediatype for Data.

Extension Mediatype Resources Comment
ATOM application/atom+xml Category, Version, Specifications, Drainage Basins, Reference System This is the default mediatype for all resources except Data. If no suffix is specified in the request to these resources, then ATOM is used.
XML application/xml Category, Version, Specifications, Drainage Basins, Reference System This mediatype is based on a set of xml-schema and is the primary mediatype for the API
JSON application/json Category, Version, Specifications, Drainage Basins, Reference System This mediatype is not based on any schema but should be stable enough to build upon
ZIP application/zip Data This mediatype is used for Data only. It is not used for other resources.

HTTP codes

You should write your application to handle any HTTP code, but the following is most common

Code Comment
200 The request is ok and you can consume the resource.
404 The request points to a resource that do not exist. This might happen if you query for a apecification, drainage basin or Reference system that does not exist.
500 Something went wrong internally in the system. This might be fixed after a while so try again later on.