REST API Automation

The GeoServer REST API allows for remote configuration of GeoServer and is used by GeoCat Bridge.

The most common goal for automation, which is used in the examples below, is to duplicate several layers to a newly created workspace.

Adapting a workspace example

Reference:

https://docs.geoserver.org/latest/en/api/#1.0.0/workspaces.yaml

To start we will duplicate a workspace definition, which is defined by two REST resources workspace (for service definition) and namespace (for xml documents).

To retrieve a workspace test definition in json:

curl -v -u admin:geoserver -XGET -H "Content-type: text/json" \
    http://localhost:8080/geoserver/rest/workspaces/test \
    -o workspace.json

{
  "workspace": {
    "name": "test",
    "isolated": false,
    "dateCreated": "2022-05-27 22:27:15.235 UTC",
    "dataStores": "http://localhost:8080/geoserver/rest/workspaces/test/datastores.json",
    "coverageStores": "http://localhost:8080/geoserver/rest/workspaces/test/coveragestores.json",
    "wmsStores": "http://localhost:8080/geoserver/rest/workspaces/test/wmsstores.json",
    "wmtsStores": "http://localhost:8080/geoserver/rest/workspaces/test/wmtsstores.json"
  }
}

Edit workspace.json as template for example workspace:

{
  "workspace": {
    "name": "example",
    "isolated": false
  }
}

To retrieve a namespace test definition in json:

curl -v -u admin:geoserver -XGET -H "Content-type: text/json" \
    http://localhost:8080/geoserver/rest/namespaces/test \
    -o namespace.json

{
    "namespace": {
        "prefix": "example",
        "uri": "http://localhost:8080/example",
        "isolated": false
    }
}

Edit namespace.json as a template for example namespace:

{
  "workspace": {
    "name": "example",
    "isolated": false
  }
}

Create example workspace:

curl -v -u admin:geoserver -XPOST -T workspace.json -H "Content-type: application/json" \
    http://localhost:8080/geoserver/rest/workspaces

< HTTP/1.1 201

The HTTP 201 Created indicates the workspace was created successfully. Indeed the workspace has been created and a placeholder namespace has already been generated.

With this in mind we can edit the already created example namespace using PUT:

curl -v -u admin:geoserver -XPUT -T namespace.json -H "Content-type: application/json" \
    http://localhost:8080/geoserver/rest/namespaces/example

< HTTP/1.1 100

HTTP status code 100 Continue is returned indicating we should continue.

Uploaded resources including data

Managing data files is a challenge on a remote server:

GeoCat Live includes a WebDAV folder mapped to the GEOSERVER_DATA_DIR/data location, this location can be managed using cURL and http commands, or mounted as a network drive for data management.
The GeoServer rest/resources endpoint is intended for managing config files, icons and fonts - but can also be used to manage.

Reference:

https://docs.geoserver.org/latest/en/api/#1.0.0/resource.yaml

Instructions:

Using sample GeoTIFF from https://www.terracolor.net/samples/ :

NextGen_Perth_AU_15m_Geo.prj NextGen_Perth_AU_15m_Geo.tfw NextGen_Perth_AU_15m_Geo.tif NextGen_Perth_AU_15m_Geo.txt

Upload using cURL:

curl -w "\n%{http_code}\n" -u admin:geoserver -XPUT -T NextGen_Perth_AU_15m_Geo.prj \
    http://localhost:8080/geoserver/rest/resource/data/terracolor/NextGen_Perth_AU_15m_Geo.prj

curl -w "%{http_code}\n" -u admin:geoserver -XPUT -T NextGen_Perth_AU_15m_Geo.tfw \
    http://localhost:8080/geoserver/rest/resource/data/terracolor/NextGen_Perth_AU_15m_Geo.tfw

curl -w "%{http_code}\n" -u admin:geoserver -XPUT -T NextGen_Perth_AU_15m_Geo.tif \
    http://localhost:8080/geoserver/rest/resource/data/terracolor/NextGen_Perth_AU_15m_Geo.tif

curl -w "%{http_code}\n" -u admin:geoserver -XPUT -T NextGen_Perth_AU_15m_Geo.txt \
    http://localhost:8080/geoserver/rest/resource/data/terracolor/NextGen_Perth_AU_15m_Geo.txt

The resources endpoint is very relaxed, and will create any folder needed to upload the resource into the requested location. In the example above the folder data/terracoloris created as needed.
```
curl -w "\n%{http_code}\n%{header_json}\n" -u admin:geoserver -XDELETE \
    http://localhost:8080/geoserver/rest/resource/data/terracolor/
```
```
    200
```

Adapting a coverage store example

Reference:

https://docs.geoserver.org/latest/en/api/#1.0.0/resource.yaml

Instructions:

To retrieve a coverage store test Terracolor definition in json:
```
curl -v -u admin:geoserver -XGET -H "Content-type: text/json" \
    http://localhost:8080/geoserver/rest/workspaces/test/coveragestores/Terracolor.json \
    -o coveragestore.json
```
This approach of using an existing coverage is an helpful way to determine all the connection parameters directly from the application.

The GeoServer application is modular with additional coverage stores and data stores added over time. This approach can be used to determine the REST API for new data formats that may not be reflected in the REST API reference.

Edit the resulting coveragestore.json with :[file:`file:data/terracolor/NextGen_Perth_AU_15m_Geo.tif]{.title-ref} connection parameter.

coveragestore.json

{
    "coverageStore": {
        "name": "Perth",
        "description": "Perth, Australia 15-meter resolution",
        "type": "WorldImage",
        "enabled": true,
        "workspace": {
            "name": "example"
        },
        "_default": false,
        "url": "file:data/terracolor/NextGen_Perth_AU_15m_Geo.tif"
    }
}

And create new Perth coverage store:

curl -v -u admin:geoserver -XPOST -T coveragestore.json -H "Content-type: application/json" \
     http://localhost:8080/geoserver/rest/workspaces/example/coveragestores

HTTP/1.1 201

Perth

Adapting a coverage example

A coverage is defined by two REST resources coverages (for data definition) and layer (for publication).

Reference:

Instructions:

To retrieve a coverage test:sydney definition in json from the workspace:

curl -v -u admin:geoserver -XGET -H "Content-type: text/json" \
    http://localhost:8080/geoserver/rest/workspaces/test/coverages/sydney.json \
    -o coverage.json

Or retrieve from test: Terracolor coverage store:

curl -v -u admin:geoserver -XGET -H "content-type: application/json" \
    http://localhost:8080/geoserver/rest/workspaces/test/coveragestores/Terracolor/coverages/sydney.json \
    -o coverage.json

A lot of the details will be filled in when the instance is created, edit coverage.json down to the bare essentials. In this case GeoServer was not able to match the provided prj file so we have included the srs information.`
coverage.json
```
{
    "coverage": {
        "name": "perth",
        "nativeName": "NextGen_Perth_AU_15m_Geo",
        "srs": "EPSG:4326"
    }
}
```

And create new perth coverage:

curl -v -u admin:geoserver -XPOST -T coverage.json -H "Content-type: application/json" \
    http://localhost:8080/geoserver/rest/workspaces/example/coveragestores/Perth/coverages

To retrieve layer publishing details for the new layer:

curl -v -u admin:geoserver -XGET -H \"content-type: application/json" \ 
    http://localhost:8080/geoserver/rest/workspaces/example/layers/perth.json -o layer.json

Compare with a working example to learn the json representation of different configuration options.
- Retrieve the existing layer.json definition
- Make the appropriate changes
- Use PUT to update the layer definition in place
If you are more comfortable with an xml toolchain text/xml is available.