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 |