API details

This page contains information on the REST API architecture.

Authentication

REST requires that the client be authenticated. By default, the method of authentication used is Basic authentication. See the Security section for how to change the authentication method.

Status codes

An HTTP request uses a status code to relay the outcome of the request to the client. Different status codes are used for various purposes throughout this document. These codes are described in detail by the HTTP specification.

The most common status codes are listed below, along with their descriptions:

Status code

Description

Notes

200

OK

The request was successful

201

Created

A new resource was successfully created, such as a new feature type or data store

403

Forbidden

Often denotes a permissions mismatch

404

Not Found

Endpoint or resource was not at the indicated location

405

Method Not Allowed

Often denotes an endpoint accessed with an incorrect operation (for example, a GET request where a PUT/POST is indicated)

500

Internal Server Error

Often denotes a syntax error in the request

Formats and representations

A format specifies how a particular resource should be represented. A format is used:

  • In an operation to specify what representation should be returned to the client

  • In a POST or PUT operation to specify the representation being sent to the server

In a GET operation the format can be specified in two ways.

There are two ways to specify the format for a GET operation. The first option uses the Accept header. For example, with the header set to "Accept: text/xml" the resource would be returned as XML. The second option of setting the format is via a file extension. For example, given a resource foo, to request a representation of foo as XML, the request URI would end with /foo.xml. To request a representation as JSON, the request URI would end with /foo.json. When no format is specified the server will use its own internal format, usually HTML. When the response format is specified both by the header and by the extension, the format specified by the extension takes precedence.

In a POST or PUT operation, the format of content being sent to the server is specified with the Content-type header. For example, to send a representation in XML, use "Content-type: text/xml" or "Content-type: application/xml". As with GET requests, the representation of the content returned from the server is specified by the Accept header or by the format.

The following table defines the Content-type values for each format:

Format

Content-type

XML

application/xml

JSON

application/json

HTML

application/html

SLD

application/vnd.ogc.sld+xml

ZIP

application/zip