REST API

Overview

Endpoint	URL	GET	POST	PATCH	DELETE
Layers	`/rest/layers`	GET	x	x	x
Workspace Layers	`/rest/workspaces/<workspace_name>/layers`	GET	POST	x	DELETE
Workspace Layer	`/rest/workspaces/<workspace_name>/layers/<layername>`	GET	x	PATCH	DELETE
Workspace Layer Thumbnail	`/rest/workspaces/<workspace_name>/layers/<layername>/thumbnail`	GET	x	x	x
Workspace Layer Style	`/rest/workspaces/<workspace_name>/layers/<layername>/style`	GET	x	x	x
Workspace Layer Chunk	`/rest/workspaces/<workspace_name>/layers/<layername>/chunk`	GET	POST	x	x
Workspace Layer Metadata Comparison	`/rest/workspaces/<workspace_name>/layers/<layername>/metadata-comparison`	GET	x	x	x
Maps	`/rest/maps`	GET	x	x	x
Workspace Maps	`/rest/workspaces/<workspace_name>/maps`	GET	POST	x	DELETE
Workspace Map	`/rest/workspaces/<workspace_name>/maps/<mapname>`	GET	x	PATCH	DELETE
Workspace Map File	`/rest/workspaces/<workspace_name>/maps/<mapname>/file`	GET	x	x	x
Workspace Map Thumbnail	`/rest/workspaces/<workspace_name>/maps/<mapname>/thumbnail`	GET	x	x	x
Workspace Map Metadata Comparison	`/rest/workspaces/<workspace_name>/layers/<layername>/metadata-comparison`	GET	x	x	x
Users	`/rest/users`	GET	x	x	x
Current User	`/rest/current-user`	GET	x	PATCH	DELETE
Version	`/rest/about/version`	GET	x	x	x

REST path parameters

workspace_name, string ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
- string identifying workspace

NOTE: Before version 1.10.0, workspace-related endpoints did not include /workspaces in their path. These old endpoints are still functional, but deprecated. More specifically, they return HTTP header Deprecation. If you get such header in response, rewrite your client to use new endpoint path. Old endpoints will stop working in the next major release.

Layers

URL

/rest/layers

GET Layers

Get list of published layers.

Request

Query parameters:

full_text_filter: String. Only layers satisfying any of following conditions are returned:
- Any word from input string appears in title. Search is case-insensitive, unaccent and does lemmatization for English.
- Input string appears as substring of title. Search is case-insensitive and unaccent.
bbox_filter: String. Bounding box in EPSG:3857 defined by four comma-separated coordinates minx,miny,maxx,maxy. Only layers whose bounding box intersects with given bounding box will be returned.
order_by: String. Can be one of these values:
- full_text Layers will be ordered by results of full-text search. Can be used only in combination with full_text_filter.
- title Layers will be ordered lexicographically by title value.
- last_change Layers will be ordered by time of last change. Recently updated layers will be first.
- bbox Layers will be ordered by similarity of bounding box with bounding box passed in ordering_bbox or bbox_filter. Can be used only in combination with ordering_bbox or bbox_filter.
If full_text_filter is set, default value is full_text; if bbox_filter is set, default value is bbox; otherwise default value is empty string, i.e. no ordering is guaranteed.
ordering_bbox: String. Bounding box in EPSG:3857 defined by four comma-separated coordinates minx,miny,maxx,maxy. The bounding box will be used for ordering. Can be used only if order_by is set to bbox (by default or explicitly).
limit: Non-negative Integer. No more layers than this number will be returned. But possibly less, if the query itself yields fewer layers.
offset: Non-negative Integer. Says to skip that many layers before beginning to return layers.

Response

Content-Type: application/json

JSON array of objects representing available layers with following structure:

workspace: String. Name of the layer's workspace.
name: String. Name of the layer.
title: String. Title of the layer.
uuid: String. UUID of the layer.
url: String. URL of the layer. It points to GET Workspace Layer.
updated_at: String. Date and time of last POST/PATCH of the layer. Format is ISO 8601, more specifically YYYY-MM-DDThh:mm:ss.sss±hh:mm, always in UTC. Sample value: "2021-03-18T09:29:53.769233+00:00"
access_rights:
- read: Array of strings. Names of users and roles with read access.
- write: Array of strings. Names of users and roles with write access.
bounding_box: List of 4 floats. Bounding box coordinates [minx, miny, maxx, maxy] in EPSG:3857.

Headers:

X-Total-Count: Total number of layers available from the request, taking into account all filtering parameters except limit and offset. Example "247".
Content-Range: Indicates where in a full list of layers a partial response belongs. Syntax of value is <units> <range_start>-<range_end>/<size>. Value of units is always items. Value of range_start is one-based index of the first layer within the full list, or zero if no values are returned. Value of range_end is one-based index of the last layer within the full list, or zero if no values are returned. Example: items 1-20/247.

Workspace Layers

URL

/rest/workspaces/<workspace_name>/layers

GET Workspace Layers

Get list of published layers.

Have the same request parameters and response structure and headers as GET Layers.

POST Workspace Layers

Publish vector or raster data file as new layer of WMS, in case of vector also new feature type of WFS.

Processing chain consists of few steps:

save file to workspace directory within Layman data directory
save basic information (name, title, access_rights) into PostgreSQL
for vector layers import the vector file to PostgreSQL database as new table into workspace schema, including geometry transformation to EPSG:3857
for raster layers normalize raster file to GeoTIFF in EPSG:3857 with overviews (pyramids); NoData values are normalized as transparent only if Alpha band is not available and NoData is set for each band
for vector layers publish the vector table as new layer (feature type) within appropriate WFS workspaces of GeoServer
save bounding box into PostgreSQL
for vector layers
- for layers with SLD or none style:
  - publish the table as new layer (feature type) within appropriate WMS workspaces of GeoServer
- for layers with QML style:
  - create QGS file on QGIS server filesystem with appropriate style
  - publish the layer on GeoServer through WMS cascade from QGIS server
for raster layers publish normalized GeoTIFF as new layer (coverage) on GeoServer WMS workspace
generate thumbnail image
publish metadata record to Micka (it's public if and only if read access is set to EVERYONE)
update thumbnail of each map that points to this layer

If workspace directory, database schema, GeoServer's workspaces, or GeoServer's datastores does not exist yet, it is created on demand.

Response to this request may be returned sooner than the processing chain is finished to enable asynchronous processing. Status of processing chain can be seen using GET Workspace Layer and layman_metadata.publication_status property or status properties of layer sources (wms, wfs, thumbnail, db_table, file, style, metadata) for higher granularity.

It is possible to upload data files asynchronously, which is suitable for large files. This can be done in three steps:

Send POST Workspace Layers request with file parameter filled by file names that you want to upload
Read set of files accepted to upload from POST Workspace Layers response, files_to_upload property. The set of accepted files will be either equal to or subset of file names sent in file parameter.
Send POST Workspace Layer Chunk requests using Resumable.js to upload files.

Check Asynchronous file upload example.

Request

Content-Type: multipart/form-data, application/x-www-form-urlencoded

Body parameters:

file, file(s) or file name(s)
- one of following options is expected:
  - GeoJSON file
  - ShapeFile files (at least three files: .shp, .shx, .dbf)
  - GeoTIFF (.tif or .tiff, with or without .tfw)
  - JPEG 2000 (.jp2, with or without .j2w)
  - PNG (.png, with .png.aux.xml or .pgw)
  - JPEG (.jpg, with .jpg.aux.xml or .jgw)
  - file names, i.e. array of strings
- if file names are provided, files must be uploaded subsequently using POST Workspace Layer Chunk
- in case of raster data input, following input combinations of bands and color interpretations are supported:
  - 1 band: Gray
  - 1 band: Palette
    - Transparency will be ignored. See #466 for details.
  - 2 bands: Gray, Alpha
    - Float data type with min/max values other than 0/255 may result in unexpected WMS output. See #466 for details.
  - 3 bands: Red, Green, Blue
  - 4 bands: Red, Green, Blue, Alpha
- if published file has empty bounding box (i.e. no features), its bounding box on WMS/WFS endpoint is set to the whole World
- attribute names are laundered to be safely stored in DB
- if QML style is used in this request, it must list all attributes contained in given data file
name, string
- computer-friendly identifier of the layer
- must be unique among all layers of one workspace
- by default, it is file name without extension
- will be automatically adjusted using to_safe_layer_name function
title, string .+
- human readable name of the layer
- by default it is layer name
description
- by default it is empty string
crs, string EPSG:3857 or EPSG:4326
- CRS of the file
- by default it is read/guessed from input file
style, style file
- by default default SLD style of GeoServer is used
- SLD or QML style file (recognized by the root element of XML: StyledLayerDescriptor or qgis)
  - QML style for raster data file is not supported
- uploading of additional style files, e.g. point-symbol images or fonts is not supported
- attribute names are laundered to be in line with DB attribute names
access_rights.read, string
- comma-separated names of users and roles who will get read access to this publication
- default value is current authenticated user, or EVERYONE if published by anonymous
access_rights.write, string
- comma-separated names of users and roles who will get write access to this publication
- default value is current authenticated user, or EVERYONE if published by anonymous
~~sld~~, SLD file
- deprecated parameter
- alias for style parameter

Response

Content-Type: application/json

JSON array of objects representing posted layers with following structure:

name: String. Name of the layer.
uuid: String. UUID of the layer.
url: String. URL of the layer. It points to GET Workspace Layer.
files_to_upload: List of objects. It's present only if file parameter contained file names. Each object represents one file that server expects to be subsequently uploaded using POST Workspace Layer Chunk. Each object has following properties:
- file: name of the file, equal to one of file name from file parameter
- layman_original_parameter: name of the request parameter that contained the file name; currently, the only possible value is file

DELETE Workspace Layers

Delete existing layers and all associated sources, including data file, vector DB table or normalized raster files for all layers in the workspace. The currently running asynchronous tasks of affected layers are aborted. Only layers on which user has write access right are deleted.

Request

No action parameters.

Response

Content-Type: application/json

JSON array of objects representing deleted layers:

name: String. Former name of the layer.
title: String. Former title of the layer.
uuid: String. Former UUID of the layer.
url: String. Former URL of the layer. It points to GET Workspace Layer.
access_rights:
- read: Array of strings. Names of users and roles with former read access.
- write: Array of strings. Names of users and roles with former write access.

Workspace Layer

URL

/rest/workspaces/<workspace_name>/layers/<layername>

Endpoint path parameters

layername
- layer name used for identification
- it can be obtained from responses of GET Workspace Layers, POST Workspace Layers, and all responses of this endpoint

GET Workspace Layer

Get information about existing layer.

Request

No action parameters.

Response

Content-Type: application/json

JSON object with following structure:

name: String. Layername used for identification within given workspace. It can be also used for identifying layer within WMS and WFS endpoints.
uuid: String. UUID of the layer.
layman_metadata
- publication_status: String. Can be one of these values:
  - COMPLETE: the layer is fully updated and response is final and up-to-date.
  - INCOMPLETE: some step of updating process failed, so the response is final, but missing some information.
  - UPDATING: some process is currently updating the layer (i.e. post, patch, wfs-t) so the response may change.
url: String. URL pointing to this endpoint.
title: String.
description: String.
updated_at: String. Date and time of last POST/PATCH of the publication. Format is ISO 8601, more specifically YYYY-MM-DDThh:mm:ss.sss±hh:mm, always in UTC. Sample value: "2021-03-18T09:29:53.769233+00:00"
wms
- url: String. URL of WMS endpoint. It points to WMS endpoint of appropriate GeoServer workspace.
- status: Status information about GeoServer import and availability of WMS layer. No status object means the source is available. Usual state values are
  - PENDING: publishing of this source is queued, but it did not start yet
  - STARTED: publishing of this source is in process
  - FAILURE: publishing process failed
  - NOT_AVAILABLE: source is not available, e.g. because publishing process failed
- error: If status is FAILURE, this may contain error object.
wfs, available only for vector layers
- url: String. URL of WFS endpoint. It points to WFS endpoint of appropriate GeoServer workspace.
- status: Status information about GeoServer import and availability of WFS feature type. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
thumbnail
- url: String. URL of layer thumbnail. It points to GET Workspace Layer Thumbnail.
- status: Status information about generating and availability of thumbnail. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
file
- path: String. Path to input data file. Path is relative to workspace directory.
- file_type: String. Either vector or raster depends on source file type.
- status: Status information about saving and availability of files. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
db_table, available only for vector layers
- name: String. DB table name within PostgreSQL workspace schema. This table is used as GeoServer source of layer.
- status: Status information about DB import and availability of the table. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
style
- url: String. URL of layer default style. It points to GET Workspace Layer Style.
- type: String. Type of used style. Either 'sld' or 'qml'.
- status: Status information about publishing style. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
~~sld~~
- Deprecated
- Replaced by style, contains same info
metadata
- identifier: String. Identifier of metadata record in CSW instance.
- record_url: String. URL of metadata record accessible by web browser, probably with some editing capabilities.
- csw_url: String. URL of CSW endpoint. It points to CSW endpoint of Micka.
- comparison_url: String. URL of GET Workspace Layer Metadata Comparison.
- status: Status information about metadata import and availability. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
access_rights:
- read: Array of strings. Names of users and roles with read access.
- write: Array of strings. Names of users and roles with write access.
bounding_box: List of 4 floats. Bounding box coordinates [minx, miny, maxx, maxy] in EPSG:3857.

PATCH Workspace Layer

Update information about existing layer. First, it deletes sources of the layer, and then it publishes them again with new parameters. The processing chain is similar to POST Workspace Layers.

Response to this request may be returned sooner than the processing chain is finished to enable asynchronous processing.

It is possible to upload data files asynchronously, which is suitable for large files. See POST Workspace Layers.

Calling concurrent PATCH requests is not supported, as well as calling PATCH when POST/PATCH async chain is still running, is not allowed. In such cases, error is returned.

Calling PATCH request when WFS-T async chain is still running causes abortion of WFS-T async chain and ensures another run of WFS-T async chain after PATCH async chain is finished.

Request

Content-Type: multipart/form-data, application/x-www-form-urlencoded

Parameters have same meaning as in case of POST Workspace Layers.

Body parameters:

file, file(s) or file name(s)
- If provided, current data file will be deleted and replaced by this file. GeoServer feature types, DB table, normalized raster file, and thumbnail will be deleted and created again using the new file.
- same file types as in POST Workspace Layers are expected
- if file names are provided, files must be uploaded subsequently using POST Workspace Layer Chunk
- if published file has empty bounding box (i.e. no features), its bounding box on WMS/WFS endpoint is set to the whole World
- if QML style is used (either directly within this request, or indirectly from previous state on server), it must list all attributes contained in given data file
title
description
crs, string EPSG:3857 or EPSG:4326
- Taken into account only if file is provided.
style, style file
- SLD or QML style file (recognized by the root element of XML: StyledLayerDescriptor or qgis)
  - QML style for raster data file is not supported
- attribute names are laundered to be in line with DB attribute names
- If provided, current layer thumbnail will be temporarily deleted and created again using the new style.
access_rights.read, string
- comma-separated names of users and roles who will get read access to this publication
access_rights.write, string
- comma-separated names of users and roles who will get write access to this publication
~~sld~~, SLD file
- deprecated parameter
- alias for style parameter

Response

Content-Type: application/json

JSON object, same as in case of GET Workspace Layer, possibly extended with one extra property:

files_to_upload: List of objects. It's present only if file parameter contained file names. See POST Workspace Layers response to find out more.

DELETE Workspace Layer

Delete existing layer and all associated sources, including data file, vector DB table or normalized raster file. The currently running asynchronous tasks of affected layer are aborted.

Request

No action parameters.

Response

Content-Type: application/json

JSON object representing deleted layer:

name: String. Former name of the layer.
uuid: String. Former UUID of the layer.
url: String. Former URL of the layer. It points to GET Workspace Layer.

Workspace Layer Thumbnail

URL

/rest/workspaces/<workspace_name>/layers/<layername>/thumbnail

GET Workspace Layer Thumbnail

Get thumbnail of the layer in PNG format, 300x300 px, transparent background.

Request

No action parameters.

Response

Content-Type: image/png

PNG image.

Workspace Layer Style

URL

/rest/workspaces/<workspace_name>/layers/<layername>/style

GET Workspace Layer Style

Get default style of the layer in XML format. Request is redirected to GeoServer /rest/workspaces/{workspace}/styles/{style} for layers with SLD style. For layers with QML style, response is created in Layman. Anybody can call GET, nobody can call any other method.

Request

No action parameters.

Response

Content-Type:

application/vnd.ogc.sld+xml or application/vnd.ogc.se+xml for SLD
application/x-qgis-layer-settings for QML

Workspace Layer Chunk

Layer Chunk endpoint enables to upload layer data files asynchronously by splitting them into small parts called chunks that are uploaded independently. The endpoint is expected to be operated using Resumable.js library. Resumable.js can split and upload files by chunks using HTML File API, widely supported by major browsers.

Check Asynchronous file upload example.

The endpoint is activated after POST Workspace Layers or PATCH Workspace Layer request if and only if the file parameter contained file name(s). The endpoint is active till first of the following happens:

all file chunks are uploaded
no chunk is uploaded within UPLOAD_MAX_INACTIVITY_TIME
layer is deleted

URL

/rest/<workspace_name>/layers/<layername>/chunk

GET Workspace Layer Chunk

Test if file chunk is already uploaded on the server.

Request

Query parameters:

layman_original_parameter, name of parameter of preceding request (POST Workspace Layers or PATCH Workspace Layer) that contained the file name
resumableFilename, name of file whose chunk is requested
resumableChunkNumber, serial number of requested chunk

Response

Content-Type: application/json

HTTP status code 200 if chunk is already uploaded on the server, otherwise 404.

POST Workspace Layer Chunk

Upload file chunk to the server.

Request

Content-Type: multipart/form-data

Body parameters:

file, uploaded chunk
resumableChunkNumber, serial number of uploaded chunk
resumableFilename, name of file whose chunk is uploaded
layman_original_parameter, name of parameter of preceding request (POST Workspace Layers or PATCH Workspace Layer) that contained the file name
resumableTotalChunks, number of chunks the file is split to

Response

Content-Type: application/json

HTTP status code 200 if chunk was successfully saved.

GET Workspace Layer Metadata Comparison

Get comparison of metadata properties among Layman, CSW, WMS and WFS.

Request

No action parameters.

Response

Content-Type: application/json

JSON object with one attribute:

metadata_sources: Dictionary of objects. Key is ID of metadata source valid for this JSON only (not persistent in time!). Value is object with following attributes:
- url: String. URL of the metadata source (GET Workspace Layer, CSW record, WMS Capabilities, or WFS Capabitilities).
metadata_properties: Dictionary of objects. Key is name of metadata property (e.g. reference_system). Value is object with following attributes:
- values: Dictionary of objects. Key is ID of metadata source corresponding with metadata_sources attribute. Value is any valid JSON (null, number, string, boolean, list, or object) representing value of metadata property (e.g. [3857, 4326]). Null means the value is not set.
- equal: Boolean. True if all values are considered equal, false otherwise.
- equal_or_null: Boolean. True if all values are considered equal or null, false otherwise.

Maps

URL

/rest/maps

GET Maps

Get list of published maps (map compositions).

Have the same request parameters and response structure and headers as GET Layers.

Workspace Maps

URL

/rest/workspaces/<workspace_name>/maps

GET Workspace Maps

Get list of published maps (map compositions).

Have the same request parameters and response structure and headers as GET Layers.

POST Workspace Maps

Publish new map composition. Accepts JSON valid against map-composition schema used by Hslayers-ng.

Processing chain consists of few steps:

validate JSON file against map-composition schema
save file to workspace directory
if needed, update some JSON attributes (name, title, or abstract)
generate thumbnail image
publish metadata record to Micka (it's public if and only if read access is set to EVERYONE)
save basic information (name, title, access_rights) into PostgreSQL

Some of these steps run asynchronously.

If workspace directory does not exist yet, it is created on demand.

Response to this request may be returned sooner than the processing chain is finished to enable asynchronous processing. Status of processing chain can be seen using GET Workspace Map and layman_metadata.publication_status property or status properties of map sources (file, thumbnail, metadata) for higher granularity.

Request

Content-Type: multipart/form-data

Body parameters:

file, JSON file
- must be valid against map-composition schema
name, string
- computer-friendly identifier of the map
- must be unique among all maps of one workspace
- by default, it is the first available of following options:
  - name attribute of JSON root object
  - title attribute of JSON root object
  - file name without extension
- will be automatically adjusted using to_safe_map_name function
title, string .+
- human readable name of the map
- by default it is either title attribute of JSON root object or map name
description
- by default it is either abstract attribute of JSON root object or empty string
access_rights.read, string
- comma-separated names of users and roles who will get read access to this publication
- default value is current authenticated user, or EVERYONE if published by anonymous
access_rights.write, string
- comma-separated names of users and roles who will get write access to this publication
- default value is current authenticated user, or EVERYONE if published by anonymous

Response

Content-Type: application/json

JSON array of objects representing posted maps with following structure:

name: String. Name of the map.
uuid: String. UUID of the map.
url: String. URL of the map. It points to GET Workspace Map.

DELETE Workspace Maps

Delete existing maps and all associated sources, including map-composition JSON file and map thumbnail for all maps in the workspace. The currently running asynchronous tasks of affected maps are aborted. Only maps on which user has write access right are deleted.

Request

No action parameters.

Response

Content-Type: application/json

JSON array of objects representing deleted maps:

name: String. Former name of the map.
title: String. Former title of the map.
uuid: String. Former UUID of the map.
url: String. Former URL of the map. It points to GET Workspace Map.
access_rights:
- read: Array of strings. Names of users and roles with former read access.
- write: Array of strings. Names of users and roles with former write access.

Workspace Map

URL

/rest/workspaces/<workspace_name>/maps/<mapname>

Endpoint path parameters

mapname
- map name used for identification
- it can be obtained from responses of GET Workspace Maps, POST Workspace Maps, and all responses of this endpoint

GET Workspace Map

Get information about existing map.

Request

No action parameters.

Response

Content-Type: application/json

JSON object with following structure:

name: String. Mapname used for identification within Layman user workspace. Equal to name attribute of JSON root object
uuid: String. UUID of the map.
layman_metadata
- publication_status: String. Can be one of these values:
  - COMPLETE: map is fully updated and response is final and up-to-date.
  - INCOMPLETE: some step of updating process failed, so the response is final, but missing some information.
  - UPDATING: some process is currently updating the map (i.e. post, patch, wfs-t) so the response may change.
url: String. URL pointing to this endpoint.
title: String. Taken from title attribute of JSON root object
description: String. Taken from abstract attribute of JSON root object.
updated_at: String. Date and time of last POST/PATCH of the publication. Format is ISO 8601, more specifically YYYY-MM-DDThh:mm:ss.sss±hh:mm, always in UTC. Sample value: "2021-03-18T09:29:53.769233+00:00"
file
- url: String. URL of map-composition JSON file. It points to GET Workspace Map File.
- path: String. Path to map-composition JSON file, relative to workspace directory.
- status: Status information about availability of file. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
thumbnail
- url: String. URL of map thumbnail. It points to GET Workspace Map Thumbnail.
- status: Status information about generating and availability of thumbnail. See GET Workspace Layer wms property for meaning.
- error: If status is FAILURE, this may contain error object.
metadata
- identifier: String. Identifier of metadata record in CSW instance.
- record_url: String. URL of metadata record accessible by web browser, probably with some editing capabilities.
- csw_url: String. URL of CSW endpoint. It points to CSW endpoint of Micka.
- comparison_url: String. URL of GET Workspace Map Metadata Comparison.
- status: Status information about metadata import and availability. See GET Workspace Map
- error: If status is FAILURE, this may contain error object.
access_rights:
- read: Array of strings. Names of users and roles with read access.
- write: Array of strings. Names of users and roles with write access.
bounding_box: List of 4 floats. Bounding box coordinates [minx, miny, maxx, maxy] in EPSG:3857.

PATCH Workspace Map

Update information about existing map. First, it deletes sources of the map, and then it publishes them again with new parameters. The processing chain is similar to POST Workspace Maps, including asynchronous tasks,

Calling concurrent PATCH requests is not supported, as well as calling PATCH when POST/PATCH async chain is still running, is not allowed. In such cases, error is returned.

Calling PATCH request when WFS-T async chain is still running causes abortion of WFS-T async chain and ensures another run of WFS-T async chain after PATCH async chain is finished.

Request

Content-Type: multipart/form-data, application/x-www-form-urlencoded

Parameters have same meaning as in case of POST Workspace Maps.

Body parameters: file, JSON file

If provided, thumbnail will be deleted and created again using the new file.
must be valid against map-composition schema
title, string .+
- human readable name of the map
- by default it is either title attribute of JSON root object or map name
description, string .+
- by default it is either abstract attribute of JSON root object or empty string
access_rights.read, string
- comma-separated names of users and roles who will get read access to this publication
access_rights.write, string
- comma-separated names of users and roles who will get write access to this publication

Response

Content-Type: application/json

JSON object, same as in case of GET Workspace Map.

DELETE Workspace Map

Delete existing map and all associated sources, including map-composition JSON file and map thumbnail. The currently running asynchronous tasks of affected map are aborted.

Request

No action parameters.

Response

Content-Type: application/json

JSON object representing deleted map:

name: String. Former name of the map.
uuid: String. Former UUID of the map.
url: String. Former URL of the map. It points to GET Workspace Map.

Workspace Map File

URL

/rest/workspaces/<workspace_name>/maps/<mapname>/file

GET Workspace Map File

Get JSON file describing the map valid against map-composition schema.

Notice that some JSON properties are automatically updated by layman, so file obtained by this endpoint may be slightly different from file that was uploaded. Expected changes:

name set to <mapname> in URL of this endpoint
title obtained from POST Workspace Maps or PATCH Workspace Map as title
abstract obtained from POST Workspace Maps or PATCH Workspace Map as description
user updated on the fly during this request:
- name set to <workspace_name> in URL of this endpoint
- email set to email of the owner, or empty string if not known
- other properties will be deleted
groups are removed

Request

No action parameters.

Response

Content-Type: application/json

JSON file describing the map valid against map-composition schema.

Workspace Map Thumbnail

URL

/rest/workspaces/<workspace_name>/maps/<mapname>/thumbnail

GET Workspace Map Thumbnail

Get thumbnail of the map in PNG format, 300x300 px, transparent background.

Request

No action parameters.

Response

Content-Type: image/png

PNG image.

GET Workspace Map Metadata Comparison

Get comparison of metadata properties among Layman and CSW.

Request

No action parameters.

Response

Content-Type: application/json

JSON object with one attribute:

metadata_sources: Dictionary of objects. Key is ID of metadata source valid for this JSON only (not persistent in time!). Value is object with following attributes:
- url: String. URL of the metadata source (GET Workspace Map, GET Workspace Map File, or CSW record).
metadata_properties: Dictionary of objects. Key is name of metadata property (e.g. reference_system). Value is object with following attributes:
- values: Dictionary of objects. Key is ID of metadata source corresponding with metadata_sources attribute. Value is any valid JSON (null, number, string, boolean, list, or object) representing value of metadata property (e.g. [3857, 4326]). Null means the value is not set.
- equal: Boolean. True if all values are considered equal, false otherwise.
- equal_or_null: Boolean. True if all values are considered equal or null, false otherwise.

Users

URL

/rest/users

GET Users

Get list of registered users.

Request.

No action parameters.

Response

Content-Type: application/json

JSON array of objects representing users of Layman with following structure:

username: String. Username of the user.
screen_name: String. Screen name of the user.
given_name: String. Given name of the user.
family_name: String. Family name of the user
middle_name: String. Middle name of the user
name: String. Whole name of the user (given_name + middle_name + family_name).

Current User

URL

/rest/current-user

GET Current User

Get information about current user.

Request

No action parameters.

Response

Content-Type: application/json

JSON object with following structure:

authenticated: Boolean. true if user is authenticated, false if user is anonymous.
claims: Object. Dictionary of known claims (e.g. name, nickname, preferred_username, or email). Claims are inspired by and have same meaning as OpenID Connect standard claims. Some claims are set even if the user is anonymous (e.g. name).
username: String. Username the user reserved within Layman. If not set, it was not reserved yet. To be used as username in some REST API paths (i.e. /rest/workspaces/<username>/...)

PATCH Current User

Update information about current user. Currently used only for reserving username.

Request

Content-Type: application/x-www-form-urlencoded

Query parameters:

adjust_username: String.
- false (default): If username sent in body parameter is already reserved by another user, Layman will return error.
- true: If username sent in body parameter is already reserved by another user or username is an empty string, layman will definitely reserve some username, preferably similar to the value sent in username body parameter or to one of claims.

Body parameters:

username: String. Username that should be reserved for current user. Username can be reserved only once and it cannot be changed. See URL parameter adjust_username for other details.

Response

Content-Type: application/json

JSON object, same as in case of GET.

DELETE Current User

Deletes current authentication credentials from Layman's cache. This should be called when user logs out from client.

Request

No action parameters.

Response

Content-Type: application/json

HTTP status code 200 if credentials were deleted.

Version

URL

/rest/about/version

GET Version

Get information about current application version.

Request

No action parameters.

Response

Content-Type: application/json

JSON object representing current application version:

about
- applications: Object with information about each application.
  - layman:
    - version: String. The current version of Layman app. In semantic versioning format X.Y.Z, with suffix -dev for the development version.
    - release-timestamp: Datetime. Date and time of the release. For development version, date and time of the last public release.
  - layman-test-client:
    - version: String. The current version of installed Layman test client. In semantic versioning format X.Y.Z, or commit hash for development version.
- data
  - layman:
    - last-schema-migration: String. Identifier of the last successful schema migration in format 'X.Y.Z-m'.
    - last-data-migration: String. Identifier of the last successful data migration in format 'X.Y.Z-m'.
    - last-migration:
      - deprecated parameter
      - alias for last-schema-migration parameter

Files

rest.md

Latest commit

History

rest.md

File metadata and controls

REST API

Overview

REST path parameters

Layers

URL

GET Layers

Request

Response

Workspace Layers

URL

GET Workspace Layers

POST Workspace Layers

Request

Response

DELETE Workspace Layers

Request

Response

Workspace Layer

URL

Endpoint path parameters

GET Workspace Layer

Request

Response

PATCH Workspace Layer

Request

Response

DELETE Workspace Layer

Request

Response

Workspace Layer Thumbnail

URL

GET Workspace Layer Thumbnail

Request

Response

Workspace Layer Style

URL

GET Workspace Layer Style

Request

Response

Workspace Layer Chunk

URL

GET Workspace Layer Chunk

Request

Response

POST Workspace Layer Chunk

Request

Response

GET Workspace Layer Metadata Comparison

Request

Response

Maps

URL

GET Maps

Workspace Maps

URL

GET Workspace Maps

POST Workspace Maps

Request

Response

DELETE Workspace Maps

Request

Response

Workspace Map

URL

Endpoint path parameters

GET Workspace Map

Request

Response

PATCH Workspace Map

Request

Response

DELETE Workspace Map

Request

Response