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. |