geoserver-rest-api

Project URL: https://github.com/geoserver/geoserver

REST API documentation: https://docs.geoserver.org/latest/en/user/rest/index.html

API reference: https://docs.geoserver.org/stable/en/user/rest/api/index.html

License: GNU General Public License v2.0+

Overview

GeoServer is a Java-based open-source geospatial data server that implements standard protocols such as OGC WMS, WFS, WCS, and WMTS. The GeoServer REST API provides a complete RESTful configuration management interface, enabling programmatic management of various GeoServer resources through standard HTTP methods (GET / POST / PUT / DELETE).

Typical uses of the REST API include:

• Automated deployment: batch creation of workspaces, data stores, and published layers
• CI/CD integration: automatically configure GeoServer in continuous integration pipelines
• AI agents: enable AI to autonomously manage map services through HTTP interfaces
• Operations scripts: batch modify styles and update data source connection parameters

Base URL format: http://{host}:{port}/geoserver/rest

Default authentication: username admin, password geoserver（HTTP Basic Auth）

Data format: Supports JSON and XML, specified via the Accept / Content-Type request header or URL suffix (.json / .xml).

---

Authentication Methods

All write operations (POST / PUT / DELETE) require authentication. GeoServer uses HTTP Basic Auth by default:

# curl 方式
curl -u admin:geoserver ...

# HTTP Header 方式
Authorization: Basic YWRtaW46Z2Vvc2VydmVy

---

API Endpoints Overview

System Management

Operation	Method	Endpoint	Description
Get version information	GET	/rest/about/version.json	Returns GeoServer version and component information
Get system status	GET	/rest/about/system-status.json	Returns system operating status
Get manifest	GET	/rest/about/manifest.json	Returns the manifest of loaded modules
Reload configuration	POST	/rest/reload	Reload configuration from disk
Reset cache	POST	/rest/reset	Reset the resource cache in memory

Workspaces

Operation	Method	Endpoint	Description
List all workspaces	GET	/rest/workspaces.json	Returns the list of workspaces
Create workspace	POST	/rest/workspaces	Create a new workspace
Get workspace details	GET	/rest/workspaces/{ws}.json	Get information about the specified workspace
Modify workspace	PUT	/rest/workspaces/{ws}	Update workspace configuration
Delete workspace	DELETE	/rest/workspaces/{ws}?recurse=true	Delete workspace (recurse=true for cascading deletion)
Get default workspace	GET	/rest/workspaces/default.json	Get the default workspace
Set default workspace	PUT	/rest/workspaces/default	Set the default workspace

Namespaces

Operation	Method	Endpoint	Description
List all namespaces	GET	/rest/namespaces.json	Returns the list of namespaces
Create namespace	POST	/rest/namespaces	Create a new namespace
Get namespace details	GET	/rest/namespaces/{ns}.json	Get the specified namespace
Modify namespace	PUT	/rest/namespaces/{ns}	Update namespace
Delete namespace	DELETE	/rest/namespaces/{ns}	Delete namespace

Data Stores — Vector Data

Operation	Method	Endpoint	Description
List data stores	GET	/rest/workspaces/{ws}/datastores.json	List the vector data stores under the workspace
Create data store	POST	/rest/workspaces/{ws}/datastores	Create a new data store
Get data store details	GET	/rest/workspaces/{ws}/datastores/{ds}.json	Get information about the specified data store
Modify data store	PUT	/rest/workspaces/{ws}/datastores/{ds}	Update data store connection parameters
Delete data store	DELETE	/rest/workspaces/{ws}/datastores/{ds}?recurse=true	Delete data store
Upload file to data store	PUT	/rest/workspaces/{ws}/datastores/{ds}/file.{ext}	Upload files such as Shapefile (ext: shp, gpkg, etc.)
Load data via URL	PUT	/rest/workspaces/{ws}/datastores/{ds}/url.{ext}	Load data from a remote URL
Externally reference data	PUT	/rest/workspaces/{ws}/datastores/{ds}/external.{ext}	Reference a server local file path

Feature Types — Vector Layer Resources

Operation	Method	Endpoint	Description
List feature types	GET	/rest/workspaces/{ws}/datastores/{ds}/featuretypes.json	List the feature types under the data store
Publish feature type	POST	/rest/workspaces/{ws}/datastores/{ds}/featuretypes	Publish a new feature type (that is, publish a vector layer)
Get feature type details	GET	/rest/workspaces/{ws}/datastores/{ds}/featuretypes/{ft}.json	Get the specified feature type
Modify feature type	PUT	/rest/workspaces/{ws}/datastores/{ds}/featuretypes/{ft}	Update feature type configuration
Delete feature type	DELETE	/rest/workspaces/{ws}/datastores/{ds}/featuretypes/{ft}?recurse=true	Delete feature type

Coverage Stores — Raster Data

Operation	Method	Endpoint	Description
List coverage stores	GET	/rest/workspaces/{ws}/coveragestores.json	List the raster data stores under the workspace
Create coverage store	POST	/rest/workspaces/{ws}/coveragestores	Create a new coverage store
Get coverage store details	GET	/rest/workspaces/{ws}/coveragestores/{cs}.json	Get the specified coverage store
Modify coverage store	PUT	/rest/workspaces/{ws}/coveragestores/{cs}	Update coverage store configuration
Delete coverage store	DELETE	/rest/workspaces/{ws}/coveragestores/{cs}?recurse=true	Delete coverage store
Upload raster file	PUT	/rest/workspaces/{ws}/coveragestores/{cs}/file.{ext}	Upload files such as GeoTIFF (ext: geotiff, worldimage, etc.)

Coverages — Raster Layer Resources

Operation	Method	Endpoint	Description
List coverages	GET	/rest/workspaces/{ws}/coveragestores/{cs}/coverages.json	List the raster resources under the coverage store
Publish coverage	POST	/rest/workspaces/{ws}/coveragestores/{cs}/coverages	Publish a new coverage
Get coverage details	GET	/rest/workspaces/{ws}/coveragestores/{cs}/coverages/{c}.json	Get the specified coverage
Modify coverage	PUT	/rest/workspaces/{ws}/coveragestores/{cs}/coverages/{c}	Update coverage configuration
Delete coverage	DELETE	/rest/workspaces/{ws}/coveragestores/{cs}/coverages/{c}?recurse=true	Delete coverage

Layers

Operation	Method	Endpoint	Description
List all layers	GET	/rest/layers.json	Return all published layers
Get layer details	GET	/rest/layers/{layer}.json	Get information for a specified layer
Modify layer	PUT	/rest/layers/{layer}	Update layer configuration (such as default style)
Delete layer	DELETE	/rest/layers/{layer}	Delete layer

Layer Groups

Operation	Method	Endpoint	Description
List layer groups (global)	GET	/rest/layergroups.json	Return the global layer group list
List layer groups (workspace)	GET	/rest/workspaces/{ws}/layergroups.json	Return the layer groups under the workspace
Create layer group	POST	/rest/layergroups	Create a global layer group
Get layer group details	GET	/rest/layergroups/{lg}.json	Get a specified layer group
Modify layer group	PUT	/rest/layergroups/{lg}	Update layer group configuration
Delete layer group	DELETE	/rest/layergroups/{lg}	Delete layer group

Styles

Operation	Method	Endpoint	Description
List styles (global)	GET	/rest/styles.json	Return the global style list
List styles (workspace)	GET	/rest/workspaces/{ws}/styles.json	Return the styles under the workspace
Create style	POST	/rest/styles	Create a new style (upload SLD/CSS)
Get style details	GET	/rest/styles/{style}.json	Get style metadata
Get style file content	GET	/rest/styles/{style}.sld	Get the raw SLD file
Update style	PUT	/rest/styles/{style}	Update style content
Delete style	DELETE	/rest/styles/{style}?purge=true	Delete style (purge=true also deletes the file)

OGC Service Settings

Operation	Method	Endpoint	Description
Get WMS global settings	GET	/rest/services/wms/settings.json	Get WMS service configuration
Modify WMS global settings	PUT	/rest/services/wms/settings	Update WMS configuration
Get WFS global settings	GET	/rest/services/wfs/settings.json	Get WFS service configuration
Modify WFS global settings	PUT	/rest/services/wfs/settings	Update WFS configuration
Get WCS global settings	GET	/rest/services/wcs/settings.json	Get WCS service configuration
Modify WCS global settings	PUT	/rest/services/wcs/settings	Update WCS configuration
Get WMTS global settings	GET	/rest/services/wmts/settings.json	Get WMTS service configuration
Modify WMTS global settings	PUT	/rest/services/wmts/settings	Update WMTS configuration
Workspace-level service settings	GET/PUT	/rest/services/wms/workspaces/{ws}/settings.json	Workspace-level WMS configuration

Security

Operation	Method	Endpoint	Description
Get master password information	GET	/rest/security/masterpw.json	Get master password status
Modify master password	PUT	/rest/security/masterpw	Update master password
Get data security rules	GET	/rest/security/acl/layers.json	Get layer access control rules
Set data security rules	POST	/rest/security/acl/layers	Add layer access control rules
Get service security rules	GET	/rest/security/acl/services.json	Get service access control rules
Get REST security rules	GET	/rest/security/acl/rest.json	Get REST endpoint access rules
List users	GET	/rest/security/usergroup/users.json	List all users
Create user	POST	/rest/security/usergroup/users	Create a new user
List roles	GET	/rest/security/roles.json	List all roles

GeoWebCache Integration

Operation	Method	Endpoint	Description
Get layer cache settings	GET	/rest/layers/{layer}/gwc	Get the GWC cache configuration for a layer
Modify layer cache settings	PUT	/rest/layers/{layer}/gwc	Update layer cache configuration
Clear layer cache (Seed)	POST	/gwc/rest/seed/{layer}.json	Initiate a cache seed/reseed/truncate task
View cache task status	GET	/gwc/rest/seed/{layer}.json	Get cache task progress
Terminate cache task	POST	/gwc/rest/seed/{layer}	Terminate a running cache task
Batch truncate	POST	/gwc/rest/masstruncate	Batch clear cache

---

Common Operation Examples

1. Get GeoServer Version

curl -u admin:geoserver \
  "http://localhost:8080/geoserver/rest/about/version.json"

2. Create Workspace

curl -u admin:geoserver -XPOST \
  -H "Content-Type: application/json" \
  -d '{"workspace":{"name":"myws"}}' \
  "http://localhost:8080/geoserver/rest/workspaces"

3. Create PostGIS Data Store

curl -u admin:geoserver -XPOST \
  -H "Content-Type: application/json" \
  -d '{
    "dataStore": {
      "name": "pgstore",
      "connectionParameters": {
        "entry": [
          {"@key": "host", "$": "localhost"},
          {"@key": "port", "$": "5432"},
          {"@key": "database", "$": "geodata"},
          {"@key": "user", "$": "postgres"},
          {"@key": "passwd", "$": "postgres"},
          {"@key": "dbtype", "$": "postgis"},
          {"@key": "schema", "$": "public"}
        ]
      }
    }
  }' \
  "http://localhost:8080/geoserver/rest/workspaces/myws/datastores"

4. Upload Shapefile and Automatically Publish Layer

curl -u admin:geoserver -XPUT \
  -H "Content-Type: application/zip" \
  --data-binary @roads.zip \
  "http://localhost:8080/geoserver/rest/workspaces/myws/datastores/roads/file.shp"

After upload, a data store and layer with the same name are automatically created. The Shapefile must be packaged as a ZIP (containing .shp, .shx, .dbf, .prj files).

5. Publish PostGIS Table as Feature Type

curl -u admin:geoserver -XPOST \
  -H "Content-Type: application/json" \
  -d '{"featureType":{"name":"buildings","nativeName":"buildings"}}' \
  "http://localhost:8080/geoserver/rest/workspaces/myws/datastores/pgstore/featuretypes"

6. Upload GeoTIFF Raster Data

curl -u admin:geoserver -XPUT \
  -H "Content-Type: image/tiff" \
  --data-binary @dem.tif \
  "http://localhost:8080/geoserver/rest/workspaces/myws/coveragestores/dem/file.geotiff"

7. Create and Upload SLD Style

# 步骤 1：创建样式定义
curl -u admin:geoserver -XPOST \
  -H "Content-Type: application/json" \
  -d '{"style":{"name":"mystyle","filename":"mystyle.sld"}}' \
  "http://localhost:8080/geoserver/rest/workspaces/myws/styles"

# 步骤 2：上传 SLD 文件内容
curl -u admin:geoserver -XPUT \
  -H "Content-Type: application/vnd.ogc.sld+xml" \
  --data-binary @mystyle.sld \
  "http://localhost:8080/geoserver/rest/workspaces/myws/styles/mystyle"

8. Set Default Style for Layer

curl -u admin:geoserver -XPUT \
  -H "Content-Type: application/json" \
  -d '{"layer":{"defaultStyle":{"name":"mystyle","workspace":"myws"}}}' \
  "http://localhost:8080/geoserver/rest/layers/myws:roads"

9. Create Layer Group

curl -u admin:geoserver -XPOST \
  -H "Content-Type: application/json" \
  -d '{
    "layerGroup": {
      "name": "basemap",
      "layers": {
        "layer": [
          {"name": "myws:roads"},
          {"name": "myws:buildings"}
        ]
      },
      "styles": {
        "style": [
          {"name": "line"},
          {"name": "polygon"}
        ]
      }
    }
  }' \
  "http://localhost:8080/geoserver/rest/workspaces/myws/layergroups"

10. Delete Workspace (Cascade Delete All Content)

curl -u admin:geoserver -XDELETE \
  "http://localhost:8080/geoserver/rest/workspaces/myws?recurse=true"

---

Typical Workflows

Complete Process for Publishing Vector Data (Shapefile)

1. POST /rest/workspaces               → 创建工作空间
2. PUT  .../datastores/{ds}/file.shp   → 上传 Shapefile（自动创建数据存储和图层）
3. POST /rest/workspaces/{ws}/styles   → 创建样式
4. PUT  .../styles/{style}             → 上传 SLD 文件
5. PUT  /rest/layers/{layer}           → 绑定样式到图层

Complete Process for Publishing Vector Data (PostGIS)

1. POST /rest/workspaces                       → 创建工作空间
2. POST .../datastores                          → 创建 PostGIS 数据存储
3. POST .../datastores/{ds}/featuretypes        → 发布数据库表为图层
4. PUT  /rest/layers/{layer}                    → 配置图层样式

Complete Process for Publishing Raster Data (GeoTIFF)

1. POST /rest/workspaces                            → 创建工作空间
2. PUT  .../coveragestores/{cs}/file.geotiff        → 上传 GeoTIFF（自动创建存储和覆盖）
3. PUT  /rest/layers/{layer}                        → 配置图层样式

---

Request and Response Formats

JSON Format Conventions

When using JSON for requests and responses, note GeoServer's JSON wrapper structure:

// 工作空间列表响应
{
  "workspaces": {
    "workspace": [
      {"name": "cite", "href": "http://..."},
      {"name": "tiger", "href": "http://..."}
    ]
  }
}

// 单个工作空间响应
{
  "workspace": {
    "name": "myws",
    "isolated": false,
    "dataStores": "http://...",
    "coverageStores": "http://...",
    "wmsStores": "http://..."
  }
}

Common Content-Types

Format	Content-Type
JSON	application/json
XML	application/xml or text/xml
SLD	application/vnd.ogc.sld+xml
ZIP (Shapefile)	application/zip
GeoTIFF	image/tiff
GeoPackage	application/geopackage+sqlite3

HTTP Status Codes

Status Code	Meaning
200	Request successful
201	Resource created successfully
401	Authentication failed
403	Insufficient permissions
404	Resource does not exist
405	Method not allowed
500	Internal server error

---

Important Notes

1. Authentication required: All modification operations (POST / PUT / DELETE) must provide valid authentication credentials.
2. recurse parameter: When deleting a workspace or data store, add ?recurse=true to cascade delete all sub-resources; otherwise, deletion will fail if sub-resources exist.
3. JSON wrapping: GeoServer REST API JSON request/response bodies all use a single-layer wrapper object (such as {"workspace":{...}}), which differs from standard REST practices and requires attention when using.
4. URL suffix: You can use the .json or .xml suffix instead of the Accept request header to specify the response format.
5. File upload: When uploading a Shapefile, it must be packaged in ZIP format, and the ZIP must contain the .shp、.shx、.dbf、.prj file.
6. Encoding: It is recommended to use English letters, numbers, and underscores for layer names and workspace names, avoiding Chinese characters and special characters.
7. GeoWebCache: After modifying a layer via the REST API, you may need to manually clear the GWC cache for that layer to see the updates.

---

Reference Links

• GeoServer source code repository:https://github.com/geoserver/geoserver
• REST API overview:https://docs.geoserver.org/latest/en/user/rest/index.html
• REST API reference:https://docs.geoserver.org/stable/en/user/rest/api/index.html
• GeoServer user manual:https://docs.geoserver.org/stable/en/user/