Base URL & HTTP Methods

Understanding the foundational structure of the GeoServer REST API endpoint paths and the standard HTTP verbs used to interact with geospatial resources.

Note: The REST API is designed for programmatic administration. It is not intended for direct client-side browser usage in production without proper CORS configuration. Always use server-to-server calls or a secure backend proxy.

Constructing the Base URL

All REST API requests follow a consistent URL structure. The base path is always appended to your GeoServer instance's root URL.

URL Structure

{protocol}://{hostname}:{port}/geoserver/rest/

Common Deployment Examples

Local Development: http://localhost:8080/geoserver/rest/
Docker Container: http://<container-ip>:8080/geoserver/rest/
Cloud/Proxy: https://maps.example.com/api/geoserver/rest/

Important: Always include the trailing slash / on the base URL. Omitting it may result in 404 Not Found errors depending on your reverse proxy configuration.

HTTP Methods Overview

GeoServer's REST API adheres to standard RESTful conventions. The following HTTP methods define how you interact with resources:

GET

Read / Retrieve

Fetch resource configurations, lists, or metadata without modifying state.

POST

Create / Modify

Create new resources or update existing ones by submitting XML/JSON payloads.

PUT

Replace

Full replacement of a resource at a specific endpoint path.

DELETE

Remove

Permanently delete a resource. Use with caution as most operations are irreversible.

Request Examples

Below are standard curl examples demonstrating each method against the base URL:

GET - List Workspaces

curl -u admin:geoserver -X GET \
  "http://localhost:8080/geoserver/rest/workspaces.json"

POST - Create Workspace

curl -u admin:geoserver -X POST \
  -H "Content-Type: text/xml" \
  -d '<workspace><name>new_proj</name></workspace>' \
  "http://localhost:8080/geoserver/rest/workspaces"

DELETE - Remove Layer

curl -u admin:geoserver -X DELETE \
  "http://localhost:8080/geoserver/rest/workspaces/myws/coveragestores/mycs/coverages/mycov"

Response Formats

By default, GeoServer returns application/xml. You can request JSON by appending .json to the endpoint or setting the Accept header:

Headers

Accept: application/json
Content-Type: application/json  # For POST/PUT payloads

Authentication & CORS

Write operations (POST, PUT, DELETE) require authentication. Basic Auth is supported, but OAuth2 or JWT token-based auth is recommended for production. The REST API does not enable CORS by default; configure your reverse proxy (Nginx/Apache) if cross-origin requests are needed.

Security Best Practice: Never expose the /rest/ endpoint directly to the public internet without firewall rules, IP whitelisting, or a dedicated API gateway.