OGC API - Features - Part 4: Create, Replace, Update and Delete (original) (raw)

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD.

THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

Table of Contents

• 1. Scope
• 2. Conformance
• 3. References
• 4. Terms, definitions and abbreviated terms
  • 4.1. Terms and Definitions
    * 4.1.1. endpoint
    * 4.1.2. resources endpoint
    * 4.1.3. resource endpoint
    * 4.1.4. optimistic locking
• 5. Conventions and background
  • 5.1. General remarks
  • 5.2. Identifiers
  • 5.3. Sequence diagrams
  • 5.4. Dependencies to other requirements classes
• 6. Requirements Class "Create/Replace/Delete"
  • 6.1. Overview
    * 6.1.1. HTTP status codes
    * 6.1.2. Cross-origin requests
    * 6.1.3. Schemas
  • 6.2. Adding a new resource to a collection (CREATE)
    * 6.2.1. Sequence diagram
    * 6.2.2. Operation
    * 6.2.3. Request body
    * 6.2.4. Response
    * 6.2.5. Exceptions
    * 6.2.6. Example
  • 6.3. Replacing an existing resource (REPLACE)
    * 6.3.1. Sequence diagram
    * 6.3.2. Operation
    * 6.3.3. Request body
    * 6.3.4. Overview
    * 6.3.5. Response
    * 6.3.6. Exceptions
    * 6.3.7. Example
  • 6.4. Removing a resource from a collection (DELETE)
    * 6.4.1. Sequence diagram
    * 6.4.2. Operation
    * 6.4.3. Response
    * 6.4.4. Exceptions
    * 6.4.5. Example
  • 6.5. Determining available methods at an endpoint (OPTIONS)
    * 6.5.1. Overview
    * 6.5.2. Sequence diagram
    * 6.5.3. Operation
    * 6.5.4. Request body
    * 6.5.5. Response
    * 6.5.6. Exceptions
    * 6.5.7. Examples
• 7. Requirements Class "Update"
  • 7.1. Overview
  • 7.2. Modifying an existing resource (UPDATE)
    * 7.2.1. Sequence diagram
    * 7.2.2. Operation
    * 7.2.3. Request body
    * 7.2.4. Response
    * 7.2.5. Exceptions
    * 7.2.6. Example
  • 7.3. Adding and removing resources properties
• 8. Requirements Class "Optimistic Locking"
  • 8.1. Overview
  • 8.2. Optimistic locking using timestamps
    * 8.2.1. Overview
    * 8.2.2. Last-modified
    * 8.2.3. Conditional processing
    * 8.2.4. Example
  • 8.3. Optimistic locking with ETags
    * 8.3.1. Overview
    * 8.3.2. Entity tags
    * 8.3.3. Conditional processing
    * 8.3.4. Example
  • 8.4. Exceptions
• 9. Requirements Class "Features"
  • 9.1. Overview
  • 9.2. Resources endpoint
  • 9.3. Resource endpoint
  • 9.4. Support for creating features using the PUT method
  • 9.5. Coordinate reference systems (CRS)
  • 9.6. Feature schemas
  • 9.7. JSON Merge Patch
  • 9.8. GeoJSON
  • 9.9. Geography Markup Language (GML)
• 10. Media Types
• 11. Security Considerations
• Annex A: Abstract Test Suite (Normative)
• Annex B: Revision History
• Annex C: Bibliography

i. Abstract

OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

OGC API - Features - Part 4: Create, Replace, Update and Delete Standard (hereafter also referred to as "this Standard" or "this document") defines the behavior of an API that allows resource instances to be added, replaced, modified and/or removed for a collection.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

OGC API resource feature collection instance spatial data openapi transactions insert update delete add modify remove REST PUT POST DELETE PATCH

iii. Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iv. Submitting organizations

The following organizations submitted this document to the Open Geospatial Consortium (OGC):

• CubeWerx Inc.
• interactive instruments GmbH

v. Submitters

All questions regarding this submission should be directed to the editors or the submitters:

1. Scope

This Standard specifies an extension that defines the behavior of a server that supports operations to add, replace, modify or delete individual resources from a collection.

Specifically, this Standard specifies:

• How to add a new resource instance to a collection (i.e. create).
• How to modify an existing resource from a collection: This includes entirely replacing the existing resource (i.e. replace) or simply modifying one or more properties of a resource (i.e. update).
• How to remove an existing resource from a collection (i.e. delete).

The following table crosswalks each of the resource endpoints discussed in this Standard with the HTTP methods POST, PUT, PATCH and DELETE. Each intersecting cell in the table either contains the name of the operation for that combination of resource endpoint and HTTP method or it contains the phrase "n/a" which is used to indicate that this Standard does not specify any behavior for that combination of resource endpoint and HTTP method.

Table 1. Supported HTTP methods by resource

The option to create a new resource with PUT is conditional and depends on the characteristics of the collection.

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

• Internet Engineering Task Force (IETF). RFC 5789: PATCH Method for HTTP [online]. Edited by L. Dusseault, J. Snell. 2010 [viewed 2021-01-25]. Available at https://www.rfc-editor.org/rfc/rfc5789
• Internet Engineering Task Force (IETF). RFC 7396: JSON Merge Patch [online]. Edited by P. Hoffman, J. Snell. 2014 [viewed 2021-01-25]. Available at https://www.rfc-editor.org/rfc/rfc7396
• Internet Engineering Task Force (IETF). RFC 9110: HTTP Semantics [online]. Edited by R. Fielding, J. Reschke, M. Nottingham. 2022 [viewed 2022-11-06]. Available at https://www.rfc-editor.org/rfc/rfc9110
• Open Geospatial Consortium (OGC). OGC API - Features - Part 1: Core 1.0 [online]. Edited by C. Portele, P. Vretanos, C. Heazel. 2019 [viewed 2020-05-24]. Available at http://www.opengis.net/doc/IS/ogcapi-features-1/1.0
• Open Geospatial Consortium (OGC). OGC API - Features - Part 2: Coordinate Reference Systems by Reference 1.0 [online]. Edited by C. Portele, P. Vretanos. 2020 [viewed 2020-12-03]. Available at http://www.opengis.net/doc/IS/ogcapi-features-2/1.0
• Open Geospatial Consortium (OGC). OGC API - Features - Part 5: Schemas 1.0 (DRAFT) [online]. Edited by C. Portele, P. Vretanos. 2023 [viewed 2023-12-28]. Available at https://docs.ogc.org/DRAFTS/23-058.html

4. Terms, definitions and abbreviated terms

4.1. Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r9], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this Standard.

For the purposes of this document, the following additional terms, definitions and abbreviated terms apply in addition to those defined in OGC API - Features - Part 1: Core.

4.1.1. endpoint

a web address (URI) at which access can be gained to a service or resource [from OGC API - Features - Part 3: Filtering and the Common Query Language (CQL2]

4.1.2. resources endpoint

endpoint of the set of resource instances from a collection

EXAMPLE 1: For features or records, the endpoint is {landingPageUri}/collections/{collectionId}/items.

EXAMPLE 2: For processes, the endpoint is {landingPageUri}/processes.

4.1.3. resource endpoint

endpoint of a specific instance of a resource from a collection

EXAMPLE 1: For features, the endpoint is {landingPageUri}/collections/{collectionId}/items/{featureId}.

EXAMPLE 2: For processes, the endpoint is {landingPageUri}/processes/{processId}.

4.1.4. optimistic locking

locking protocol that resolves change conflicts at the very last moment

5. Conventions and background

See OGC API - Features - Part 1: Core, Clauses 5 and 6.

5.2. Identifiers

All requirements and conformance tests that appear in this Standard are denoted by partial URIs which are relative to this base.

5.3. Sequence diagrams

This Standard uses sequence diagrams to illustrate the flow of requests and responses between client and server.

The token <resources endpoint> is used for an endpoint that accesses resources from a collection.

EXAMPLE 1: For features, these endpoints are described by the URI template {landingPageUri}/collections/{collectionId}/items. See OGC API - Features - Part 1: Core.

EXAMPLE 2: For processes, these endpoints are described by the URI template {landingPageUri}/process. See OGC API - Processes - Part 1: Core.

The token <resource endpoint> is used for the endpoint that accesses a specific resource from a collection.

EXAMPLE 3: For features, these endpoints are described by the URI template {landingPageUri}/collections/{collectionId}/items/{featureId}. See OGC API - Features - Part 1: Core.

EXAMPLE 4: For processes, these endpoints are described by the URI template {landingPageUri}/process/{processId}. See OGC API - Processes - Part 1: Core.

5.4. Dependencies to other requirements classes

The requirements classes in this extension distinguish two types of dependencies to other Standards or requirements classes:

First, there are the "direct dependencies". Every server implementing the requirements class has to conform to the referenced Standard or requirements class.

In addition, requirements classes can also have "indirect dependencies". Servers implementing the requirements class do not have to conform to the referenced Standard or requirements class, but if they do, they have to conform to the requirements that identify the indirect dependency as a pre-condition for the normative statement.

6. Requirements Class "Create/Replace/Delete"

6.1. Overview

A server that implements this requirements class provides the ability to add, replace and/or remove individual resources from a collection. Not all operations need to be implemented for all offered mutable resources.

The HTTP POST method is used to add a new resource instance to a collection. The resource identifier is assigned by the server.

The HTTP PUT method is used to replace an existing resource in a collection with a replacement resource with the same resource identifier.

If the HTTP PUT method is executed on a non-existing resource in a collection, the server can add a new resource instance to a collection, if the collection supports that resource identifiers can be assigned by the client.

Finally, the HTTP DELETE method is used to remove a resource from a collection.

Adding or replacing a resource requires that a representation of that resource be provided by the client. This Standard does not mandate that a specific resource encoding be supported by a server.

Note that the POST, PUT and/or DELETE methods will typically only be available for authorized users with sufficient permissions. The methods available to a user are available via the OPTIONS method for each resource.

6.1.1. HTTP status codes

API clients should be prepared to handle any registered HTTP or HTTPS status code.

The Status Codes listed in Table 3 are of relevance to implementors of this Standard. Status codes 200, 201, 202, 204 and 404 are called out in this Standard’s requirements. Therefore, support for some of these status codes is mandatory for all compliant implementations. The remainder of the status codes in Table 3 are not mandatory but are important for the implementation of a well-functioning API. Support for these status codes is strongly encouraged for both client and server implementations.

Table 3. Typical HTTP status codes

More specific guidance is provided for each resource, where applicable.

The API Description Document describes the HTTP status codes generated by an API. This should not be an exhaustive list of all possible status codes. Expecting an API designer to control the use of HTTP status codes which are not generated by their software is not reasonable. Therefore, it is recommended that the API Description Document limit itself to describing HTTP status codes relevant to the proper operation of the API application logic. Client implementations should be prepared to receive HTTP status codes in addition to those described in the API Description Document.

6.1.2. Cross-origin requests

6.1.3. Schemas

This Standard makes no assumptions about any schema constraints that a server may impose upon incoming feature data. The intent is to support both "schema-less" servers (such as those back-ended by document data stores) as well as servers that have underlying schema constraints (such as those back-ended by an RDBMS).

In the "schema-less" case, as long as the incoming feature meets the requirements of the declared media type (e.g. a valid GeoJSON feature) then the resource should be created/updated with a 20x status response.

In the case where the server imposes schema constraints, the server should publish schemas to help clients create requests that are not rejected. As recommended in clause Feature schemas, schemas can be obtained from the {landingPageUri}/collections/{collectionId}/schema endpoint.

6.2. Adding a new resource to a collection (CREATE)

6.2.1. Sequence diagram

The following diagram illustrates the sequence diagram for adding a new resource to a collection.

Client Server | | | POST HTTP/1.1 | | Content-Type: | | | | ... Body contains representation of the resource ... | |-------------------------------------------------------------->| | | | HTTP/1.1 201 Created | | Location: | |<--------------------------------------------------------------|

6.2.2. Operation

6.2.3. Request body

6.2.3.1. Overview

6.2.4. Response

If the server will process the create request later, it will return a 202. In this case, the resource creation can succeed or fail, without further notification to the client about the result or the resource identifier.

6.2.5. Exceptions

See HTTP status codes.

6.2.6. Example

The following example adds a new feature to the oakland_buildings collection. The feature is represented as GeoJSON using the default CRS of http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS 84 longitude/latitude). A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

Create a New Feature Example

Client Server | | | POST /collections/oakland_buildings/items HTTP/1.1 | | Content-Type: application/geo+json | | | | { | | "type": "Feature", | | "geometry": { | | "type": "MultiPolygon", | | "coordinates": [ | | [[[-122.2694982,37.79045922],[ -122.2693624, 37.79041125], | | [-122.2693518,37.79042521],[ -122.26899, 37.7902858], | | [-122.2690027,37.79027181],[ -122.2688602, 37.79021705], | | [-122.2687222,37.790445],[-122.2688582, 37.79049813], | | [-122.2689084,37.79041634],[ -122.2689473, 37.79041058], | | [-122.2691974,37.79051029],[ -122.2692367, 37.7906097], | | [-122.2692201,37.79064271],[ -122.2693538, 37.79069243], | | [-122.2694982,37.79045922]]]] | | }, | | "properties": { | | "shape_len": 666.635209546, | | "shape_area": 14016.0452102, | | "bldgid3": "11 EMBARCADERO WEST_bldgG102", | | "bldgid2": "11 EMBARCADERO WEST", | | "bldgtype": "Commercial Building", | | "final_apn": "000O042502000", | | "apnid": 21, | | "nostory": 2, | | "bldgnum": "bldgG102", | | "numbldgs": 1, | | "comname": "Portobello Office" | | } | | } | |------------------------------------------------------------------>| | | | HTTP/1.1 201 Created | | Location: /collections/oakland_buildings/items/OB.2 | |<------------------------------------------------------------------|

6.3. Replacing an existing resource (REPLACE)

6.3.1. Sequence diagram

The following diagram illustrates the sequence diagram for replacing the content of an existing resource in a collection. The identifier of the resource does not change.

Client Server | | | PUT HTTP/1.1 | | Content-Type: | | | | ... Body contains representation of new resource content ... | |---------------------------------------------------------------->| | | | HTTP/1.1 204 OK | |<----------------------------------------------------------------|

6.3.2. Operation

In case PUT on a non-existing resource is supported, such a request can create a new resource with the resourceId specified in the URI of the resource endpoint.

To ensure that an update request is not treated as an insert, the client MAY specify an If-Match header in the update request. The service MUST NOT treat an update request containing an If-Match header as an insert.

6.3.3. Request body

6.3.4. Overview

6.3.5. Response

The status code depends on the server. If the server has updated the resource, the response is either 200 if the response includes additional content, or 204 if the response has no additional content.

If the server will process the update request later, the server will return a 202. In this case, the processing can succeed or fail, without further notification to the client.

6.3.6. Exceptions

If the server does not support the PUT method on non-existing resources, the assignment of resource identifiers is the purview of the server and as a result, clients cannot use the HTTP PUT operation to create a new resource. In this case, the creation of new resource instances has be performed using the HTTP POST operation as described in Adding a new resource to a collection (CREATE).

See also HTTP status codes.

6.3.7. Example

The following example replaces the feature created by the Create Example with a new feature. Once again, the replacement feature is represented as GeoJSON using the default CRS of http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS 84 longitude/latitude). A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

Replace an Existing Feature Example

Client Server | | | PUT /collections/oakland_buildings/items/OB.2 HTTP/1.1 | | Content-Type: application/geo+json | | | | { | | "type": "Feature", | | "id": "OB.2", | | "geometry": { | | "type": "MultiPolygon", | | "coordinates": [ | | [[[-122.2678831,37.80088484],[-122.2679268,37.80090136], | | [-122.2680801,37.80065184],[-122.2677726,37.8005301 ], | | [-122.2676158,37.80078035],[-122.2678831,37.80088484]]] | | ] | | }, | | "properties": { | | "shape_len": 402.19805753, | | "shape_area": 10117.0666708, | | "bldgid3": "258 11TH ST_bldg1", | | "bldgid2": "258 11TH ST", | | "bldgtype": "Store Building", | | "final_apn": "002 006901000", | | "apnid": 847, | | "nostory": 1, | | "bldgnum": "bldg1", | | "numbldgs": 1, | | "comname": "John Sardell & Sons" | | } | | } | |------------------------------------------------------------------>| | | | HTTP/1.1 204 OK | |<------------------------------------------------------------------|

6.4. Removing a resource from a collection (DELETE)

6.4.1. Sequence diagram

The following diagram illustrates the sequence diagram for removing a resource from a collection.

Client Server | | | DELETE HTTP/1.1 | +-------------------------------------------------------------->| | | | HTTP/1.1 204 OK | +<--------------------------------------------------------------|

6.4.2. Operation

6.4.3. Response

If the server will process the update request later, it will return a 202. In this case, the processing can succeed or fail, without further notification to the client.

6.4.4. Exceptions

See HTTP status codes.

6.4.5. Example

The following example deletes the feature created by the Create Example and replaced with a new feature in the Replace Example. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

Delete an Existing Feature Example

Client Server | | | DELETE /collections/oakland_buildings/items/OB.2 HTTP/1.1 | |-------------------------------------------------------------------->| | | | HTTP/1.1 204 OK | |<--------------------------------------------------------------------|

6.5. Determining available methods at an endpoint (OPTIONS)

6.5.1. Overview

A server is not required to implement every method described in this Standard (i.e. POST, PUT, PATCH or DELETE) for every mutable resource that it offers. Furthermore, a server that supports the ability to add, modify or remove resources from collections is not likely to be an open server. That is, access to the server, and specifically the operations that allow resource creation, modification and/or removal, will be controlled. Such controls might, for example, take the form of policy requirements (e.g. resources on this server can be inserted or updated but not deleted) or user access control requirements (e.g. user "X" is only allowed to create resources but not update or delete resources). Regardless of the controls the server must be able to advertise, within the control context in place, which methods are available for each resource that it offers. This is accomplished using the HTTP OPTIONS method.

The HTTP OPTIONS method allows the server to explicitly declare which HTTP methods are supported for a particular resource(s) endpoint. This Standard deals with the HTTP POST, PUT, PATCH and DELETE methods but any relevant HTTP method may be listed for a particular resource.

6.5.2. Sequence diagram

The following sequence diagram illustrates requesting the options available at a resource endpoint.

Client Server | | | OPTIONS HTTP/1.1 | +-------------------------------------------------------------->| | | | HTTP/1.1 200 OK | | Allow: | +<--------------------------------------------------------------|

6.5.3. Operation

6.5.4. Request body

6.5.5. Response

6.5.6. Exceptions

See HTTP status codes.

6.5.7. Examples

The following example illustrates how to get the supported HTTP methods for specific feature resources. A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

Get the OPTIONS available at the "items" endpoint.

Client Server | | | OPTIONS /collections/oakland_buildings/items HTTP/1.1 | |------------------------------------------------------------------>| | | | HTTP/1.1 200 OK | | Allow: GET, HEAD, POST | |<------------------------------------------------------------------|

Get the OPTIONS available for a specific feature.

Client Server | | | OPTIONS /collections/oakland_buildings/items/B1013 HTTP/1.1 | |------------------------------------------------------------------>| | | | HTTP/1.1 200 OK | | Allow: GET, HEAD, PUT, PATCH, DELETE | |<------------------------------------------------------------------|

7. Requirements Class "Update"

7.1. Overview

A server that implements this requirements class provides the ability to use the HTTP PATCH method to modify parts of an existing resource without the need to transmit a complete replacement resource.

Modifying parts of a resource requires that a document describing the changes to be applied be provided by the client. This Standard does not mandate that a specific encoding for this document be supported by a server.

7.2. Modifying an existing resource (UPDATE)

7.2.1. Sequence diagram

The following diagram illustrates the sequence diagram for modifying part of an existing resource by only specifying the specific parts that should be updated.

Client Server | | | PATCH HTTP/1.1 | | Content-Type: | | | | ... Body contains a document describing the changes to make | | to parts of the specified resource ... | |-------------------------------------------------------------->| | | | HTTP/1.1 204 OK | |<--------------------------------------------------------------|

7.2.2. Operation

7.2.3. Request body

Details how a PATCH request body must be processed by a server depends on the resource representation and must be specified for each resource type and its representations.

7.2.4. Response

The status code depends on the server. If the server has updated the resource, the response is either 200, if the response includes additional content such as the updated representation of the resource, or 204, if the response has no additional content.

If the server will process the update request later, it will return a 202. In this case, the processing can succeed or fail, without further notification to the client.

7.2.5. Exceptions

See HTTP status codes.

7.2.6. Example

The following example updates two properties (geom, the geometry, and apnid) and adds a new property named primary_material to the feature created by the Replace Example.

The example uses a JSON Merge Patch document to describe the changes to be made. The replacement geometry is specified using the default CRS of http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS 84 longitude/latitude). The server responds to the operation by presenting the updated feature, formatted as GeoJSON, in the response body.

Update a Portion of an Existing Feature Example

Client Server | | | PATCH /collections/oakland_buildings/items/OB.2 HTTP/1.1 | | Content-Type: application/merge-patch+json | | | | { | | "apnid": 1310, | | "primary_material": "red brick", | | "geom": { | | "coordinates": [ | | [[[-122.2679,37.8009],[-122.2679,37.8009], | | [-122.2681,37.8007],[-122.2678,37.8005], | | [-122.2676,37.8008],[-122.2679,37.8009]]] | | ] | | } | | } | |-------------------------------------------------------------------->| | | | HTTP/1.1 200 OK | | Content-Type: application/geo+json | | | | { | | "type": "Feature", | | "id": "OB.2", | | "geometry": { | | "type": "MultiPolygon", | | "coordinates": [ | | [[[-122.2679,37.8009],[-122.2679,37.8009], | | [-122.2681,37.8007],[-122.2678,37.8005], | | [-122.2676,37.8008],[-122.2679,37.8009]]] | | ] | | }, | | "properties": { | | "shape_len": 402.19805753, | | "shape_area": 10117.0666708, | | "bldgid3": "258 11TH ST_bldg1", | | "bldgid2": "258 11TH ST", | | "bldgtype": "Store Building", | | "final_apn": "002 006901000", | | "apnid": 1310, | | "nostory": 1, | | "bldgnum": "bldg1", | | "numbldgs": 1, | | "comname": "John Sardell & Sons", | | "primary_material": "red brick" | | } | | } | |<--------------------------------------------------------------------|

7.3. Adding and removing resources properties

In addition to modifying the value of existing resource properties, modifying a resource can also include adding and removing properties from the structure of a resource. For servers that are "schema-less" such mutations do not present a problem. However, for servers that include schema constraints, such mutations may result in exception conditions. In order to mitigate this possibility, the following recommendation is made:

If a server publishes a schema, update requests presented to the server should endeavor to honor the published schema.

8. Requirements Class "Optimistic Locking"

8.1. Overview

This clause specifies conformance classes that define optimistic locking mechanisms to support concurrent updates of resources.

In an environment where several clients are operating on the same resource, each client’s understanding of a resource’s state may differ from the other’s and from the server. Without some mechanism for synchronizing each client’s understanding of a resource’s state with the server, changes requested by a client that has an out-of-date understanding of the resource’s state may have undesirable effects. For example, the following sequence diagram illustrates a concurrent race condition where one client’s updates are silently lost.

Client A Server Client B | | | | GET /col...ns/oakland_buildings/items/OB.2 | | [A]|------------------------------------------->| | | | | | | GET /col...ns/oakland_buildings/items/OB.2 | | |<-------------------------------------------|[B] | | | | | HTTP/1.1 200 OK | | | Last-Modified: Sat,13 Mar 2021 11:28:17 GMT| | | ETag: 1986bf5c | | |------------------------------------------->|[C] | | | | HTTP/1.1 200 OK | | | Last-Modified: Sat,13 Mar 2021 11:28:17 GMT| | | ETag: 1986bf5c | | [D]|<-------------------------------------------| | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | [E]|------------------------------------------->| | | | | | HTTP/1.1 204 No Content | | | Last-Modified: Sun,14 Mar 2021 13:14:15 GMT| | | ETag: 66ba0c91 | | [F]|<-------------------------------------------| | | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | |<-------------------------------------------|[G] | | | | | HTTP/1.1 204 No Content | | | Last-Modified: Sun,14 Mar 2021 13:17:02 GMT| | | ETag: 11e34a43 | | |------------------------------------------->|[H]

Table 4. Example of a concurrent race condition

Optimistic locking resolves such change conflicts by exchanging state information (e.g., ETags or timestamps) between clients and servers using HTTP headers to ensure that a resource’s state has not changed between a read request to fetch a resource and a subsequent update request. If the state of the resource has changed in the intervening time interval the exchanged state information will not match and the operation fails. This necessitates a re-read of the resource to obtain the most recent state and a subsequent retry of the update operation.

This Standard supports optimistic locking using the two different types of state information supported by HTTP:

• The Last-Modified field is the date and time at which the server believes the selected representation was last modified.
• The ETag field is an opaque value (entity tag) derived by the server from the selected representation. An ETag can be strong or weak. A strong ETag requires that the representation of a resource is always byte-by-byte equal to a previous response as long as the ETag does not change. With a weak ETag the representation can change without changing the ETag as long as the server considers the representations to be semantically equivalent.

A requirements class is specified for each field, because the two options have different characteristics and API providers need to decide which option they can support.

• The ETag can be derived from the current state of the resource, while Last-Modified requires that metadata about the last change to a resource is maintained and available.
• However, all ETags must be strong ETags to support optimistic locking using HTTP. For some resources specified in OGC API Standards (for example, features), semantical equivalency would be sufficient to avoid 'lost updates'. Byte-for-byte identity is not necessary and often hard to achieve, because representations in OGC Web APIs can include various parts that can change without any semantic change to the resource and which are often dynamically created during each request. One example is self and alternate links, which can change without any change to the resource in the backend datastore (link titles can change with a new software version. An alternate link will be added, if a new encoding is supported by the API; etc.). Other changes could be differences in whitespace or differences in the sequence of members in a JSON object. Byte-for-byte identity is essential for caching and supporting range requests, but not always for PUT validation.

That is, ETags are a good option for optimistic locking when the server can provide strong ETags for all representations of a resource. Otherwise Last-Modified must be used and the metadata about changes to the resource has to be maintained. Of course, a server can also support both validator fields.

8.2. Optimistic locking using timestamps

8.2.2. Last-modified

As defined in RFC 9110: HTTP Semantics, for the purposes of this requirements class, the value of the Last-Modified header is a timestamp indicating the date and time at which the origin server believes that the selected representation was last modified, as determined at the conclusion of handling the request.

8.2.3. Conditional processing

Optimistic resource locking is implemented using the If-Unmodified-Since HTTP header. The value of the header is evaluated according to rules defined in RFC 9110 and the result of that evaluation is used to determine if the operation shall be performed or not.

If the If-Unmodified-Since HTTP header evaluation results in a value of true then the operation can proceed.

If the If-Unmodified-Since HTTP header evaluation, however, evaluates to false then the server generates a response according to the rules defined in RFC 9110. Normally, in this case, the response is a HTTP status code of 412, precondition failed. However, if the requested change is already reflected in the current state of the resource, then the server can respond with a 2xx, successful HTTP status code.

The client submitting the request will set the value of the If-Unmodified-Since header:

• To a timestamp representing the last time the representation of the resource was retrieved; or
• To the value of the Last-Modified header of the response when the representation of the resource was retrieved last.

If no If-Unmodified-Since header is provided by the client, the behavior will depend on the server. The appropriate behavior will vary depending on the dataset and use case.

8.2.4. Example

The following example, taken from the Overview, optimistically locks the resources being operated on using the If-Unmodified-Since header. Client A successfully updates the resource while Client B’s update fails. Client B, then proceeded to re-fetch the resource and try the update again.

Client A Server Client B | | | | GET /col...ns/oakland_buildings/items/OB.2 | | [A]|------------------------------------------->| | | | | | | GET /col...ns/oakland_buildings/items/OB.2 | | |<-------------------------------------------|[B] | | | | | HTTP/1.1 200 OK | | | Last-Modified: Sat,13 Mar 2021 11:28:17 GMT| | |------------------------------------------->|[C] | | | | HTTP/1.1 200 OK | | | Last-Modified: Sat,13 Mar 2021 11:28:17 GMT| | [D]|<-------------------------------------------| | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Unmodified-Since: Sat,13 Mar 2021...GMT | | [E]|------------------------------------------->| | | | | | HTTP/1.1 204 No Content | | | Last-Modified: Sun,14 Mar 2021 13:14:15 GMT| | [F]|<-------------------------------------------| | | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Unmodified-Since: Sat,13 Mar 2021...GMT | | |<-------------------------------------------|[G] | | | | | HTTP/1.1 412 Precondition Failed | | |------------------------------------------->|[H] | | | | | | | | GET /col...ns/oakland_buildings/item/OB.2 | | |<-------------------------------------------|[I] | | | | | HTTP/1.1 200 OK | | | Last-Modified: Sun,14 Mar 2021 13:14:15 GMT| | |------------------------------------------->|[J] | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Unmodified-Since: Sun,14 Mar 2021...GMT | | |<-------------------------------------------|[K] | | | | | HTTP/1.1 204 No Content | | | Last-Modified: Sun,14 Mar 2021 13:14:27 GMT| | |------------------------------------------->|[L]

Table 5. Example of a concurrent update

8.3. Optimistic locking with ETags

8.3.2. Entity tags

As defined in RFC 9110: HTTP Semantics, for the purposes of this requirements class, an ETag is an opaque token generated by the server for differentiating between multiple representations of the same resource resulting from state changes over time.

8.3.3. Conditional processing

Optimistic resource locking is implemented using the If-Match HTTP header. The value of the header is evaluated by the server according to rules defined in RFC 9110 and the result of that evaluation is used to determine if the operation shall be performed or not.

If the If-Match HTTP header evaluation by the server results in a value of true then the operation can proceed.

However, if the If-Match HTTP header evaluation by the server evaluates to false then the server generates a response according to the rules defined in RFC 9110. Normally, in this case, the server responds with a HTTP status code of 412, precondition failed. However, if the requested change is already reflected in the current state of the resource, then the server can respond with a 2xx, successful HTTP status code.

The value of the If-Match header will be a strong ETag token obtained by a preceding HTTP GET operation used to fetch a representation of the resource to be changed. Note that submitting a weak ETag token will always result in a failed precondition.

If no If-Match header is provided by the client, the behavior will depend on the server. The appropriate behavior will vary depending on the dataset and use case.

8.3.4. Example

The following example, taken from the Overview, optimistically locks the resources being operated on using the If-Match header. Client A successfully updates the resource while Client B’s update fails. Client B, then proceeded to re-fetch the resource and try the update again.

Client A Server Client B | | | | GET /col...ns/oakland_buildings/items/OB.2 | | [A]|------------------------------------------->| | | | | | | GET /col...ns/oakland_buildings/items/OB.2 | | |<-------------------------------------------|[B] | | | | | HTTP/1.1 200 OK | | | ETag: 1986bf5c | | |------------------------------------------->|[C] | | | | HTTP/1.1 200 OK | | | ETag: 1986bf5c | | [D]|<-------------------------------------------| | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Match: 1986bf5c | | [E]|------------------------------------------->| | | | | | HTTP/1.1 204 No Content | | | ETag: 66ba0c91 | | [F]|<-------------------------------------------| | | | | | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Match: 1986bf5c | | |<-------------------------------------------|[G] | | | | | HTTP/1.1 412 Precondition Failed | | |------------------------------------------->|[H] | | | | | | | | GET /col...ns/oakland_buildings/item/OB.2 | | |<-------------------------------------------|[I] | | | | | HTTP/1.1 200 OK | | | ETag: 66ba0c91 | | |------------------------------------------->|[J] | | | | | PUT /col...ns/oakland_buildings/items/OB.2 | | | If-Match: 66ba0c91 | | |<-------------------------------------------|[K] | | | | | HTTP/1.1 204 No Content | | | ETag: 7f1319eb | | |------------------------------------------->|[L]

Table 6. Example of a concurrent update

8.4. Exceptions

See HTTP status codes.

9. Requirements Class "Features"

9.2. Resources endpoint

9.3. Resource endpoint

9.4. Support for creating features using the PUT method

A collection with supportsNonAutogeneratedResourceIds set to true

{
  "title": "Cultural (Points)",
  "description": "Cultural: Information about features on the landscape that have been constructed by man.",
  "links": [ ... ],
  "id": "CulturePnt",
  "extent": {
    "spatial": {
      "bbox": [ [35.9535002, 32.5920726, 36.1085461, 32.6405082] ],
      "crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
    },
    "temporal": {
      "interval": [ ["2011-01-03T06:31:15Z", "2013-06-16T23:47:41Z"] ],
      "trs": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
    }
  },
  "itemType": "feature",
  "crs": [
    "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
    "http://www.opengis.net/def/crs/EPSG/0/3395"  ,
    "http://www.opengis.net/def/crs/EPSG/0/3857"  ,
    "http://www.opengis.net/def/crs/EPSG/0/4326"
  ],
  "storageCrs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
  "itemCount": 5,
  "supportsNonAutogeneratedResourceIds": true
}

9.5. Coordinate reference systems (CRS)

Unless the server supports OGC API - Features - Part 2: Coordinate Reference Systems by Reference, all geometries have to be submitted in the default CRS.

If the server supports OGC API - Features - Part 2: Coordinate Reference Systems by Reference, the default CRS can be overridden by declaring the Content-Crs header in the request. Alternatively, if the feature representation supports expressing CRS information for each feature / geometry, the information can also be included in the feature representation.

This approach is consistent with the use of WGS84 longitude/latitude as the default CRS for all feature-related requests in API implementation instances. If both the server and the client are CRS-aware and have the capability to handle geometries in other CRSs, this requirement enables the client to negotiate to some other mutually agreeable CRS.

Example

The following example adds a new feature to the dc_buildings collection. The feature is represented as GeoJSON and the Content-Crs HTTP header is used to assert that the geometry coordinates are expressing using CRS http://www.opengis.net/def/crs/EPSG/0/32607 (WGS 84 / UTM zone 7N). A pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server.

Create a new feature expressed using a non-default CRS.

Client Server | | | POST /collections/dc_buildings/items HTTP/1.1 | | Content-Type: application/geo+json | | Content-Crs: http://www.opengis.net/def/crs/EPSG/0/32607 | | | | { | | type: "Feature", | | geometry: { | | type: "Polygon", | | coordinates: [[ | | [6053772.741,6835449.584],[6053707.528,6835479.753], | | [6053703.657,6835471.867],[6053663.001, 6835490.725], | | [6053652.866,6835470.026],[6053681.967, 6835456.599], | | [6053681.967,6835456.599],[6053704.695, 6835446.018], | | [6053695.731,6835427.879],[6053669.296, 6835440.112], | | [6053661.758,6835425.125],[6053742.232, 6835387.872], | | [6053772.741,6835449.584]]] | | }, | | properties: { | | "bldgid2": "1732 CONNECTICUT AVE NW", | | "bldgtype": "Commercial Building", | | "final_apn": "000O042537425", | | "apnid": 73, | | "nostory": 3, | | "bldgnum": "bldgG73", | | "numbldgs": 1, | | "comname": "Acme Knitting" | | } | | } | |------------------------------------------------------------------>| | | | HTTP/1.1 201 Created | | Location: /collections/dc_buildings/items/DCB.314 | |<------------------------------------------------------------------|

If the server includes the storageCrs property in the Collection resource, as specified in OGC API - Features - Part 2: Coordinate Reference Systems by Reference, then it is recommended that client express all geometry-valued feature properties presented to the server in a request body using the storage CRS. This avoids geometric errors from the conversion of coordinates on the server when storing the geometry.

9.6. Feature schemas

Adding, replacing, or updating a feature requires that a representation of that feature or the updated properties be provided by the client. As is the case in Part 1 (Core), this Standard does not mandate that a specific feature encoding be supported by a server.

If features in a collection are constrained to a specific schema and schema information is provided by a server, the Schema resource of a collection is available at {landingPageUri}/collections/{collectionId}/schema as specified by Part 5 (Schemas). This information enables clients to generate feature representations that are acceptable to the server.

The schema identifies the feature properties that can be used in a mutation request (Receivables), that is, all properties that are not tagged as readOnly.

The mapping between the properties in the encoded feature and the properties in the JSON Schema depends on the feature encoding. This Standard provides guidance for API implementation instances that support GeoJSON.

Example

The following example fetches the schema for the oakland_buildings collection. Pseudo-sequence diagram notation is used to illustrate the details of the HTTP communication between the client and the server. Remarks:

• Since the schema includes a statement "additionalProperties": false, the server will reject any feature that has additional properties that are not specified in the schema.
• The id member is read-only as the feature identifier is assigned by the server on a POST request. In a PUT or PATCH request, the feature identifier is part of the URI.

Schema Example

Client Server | | | GET /collections/oakland_buildings/schema HTTP/1.1 | | Accept: application/schema+json | |------------------------------------------------------------------>| | | | HTTP/1.1 200 OK | | Content-Type: application/schema+json | | | | { | | "type": "object", | | "required": [ | | "id", | | "geom", | | "apnid", | | "bldgid2", | | "bldgtype", | | "final_apn" | | ], | | "additionalProperties": false, | | "properties": { | | "id": { | | "type": "string", | | "readOnly": true, | | "x-ogc-role": "id" | | }, | | "geom": { | | "format": "geometry-polygon" | | "x-ogc-role": "primary-geometry" | | }, | | "shape_len": { | | "type": "number", | | "format": "double" | | }, | | "shape_area": { | | "type": "number", | | "format": "double" | | }, | | "bldgid3": { | | "type": "string" | | }, | | "bldgid2": { | | "type": "string" | | }, | | "bldgtype": { | | "type": "string", | | "enum": ["Commercial Building", ...] | | }, | | "final_apn": { | | "type": "string", | | "pattern": "\d{13}" | | }, | | "apnid": { | | "type": "number", | | "format": "integer" | | }, | | "nostory": { | | "type": "number", | | "format": "integer", | | "minimum": 1, | | "maximum": 400 | | }, | | "bldgnum": { | | "type": "string" | | }, | | "numbldgs": { | | "type": "number", | | "format": "integer" | | }, | | "comname": { | | "type": "string" | | }, | | "primary_material": { | | "type": "string", | | "enum": ["red brick", "concrete", "wood", ...] | | } | | } | | } | |<------------------------------------------------------------------|

9.7. JSON Merge Patch

RFC 7396 (JSON Merge Patch) can be used to update selected properties of a feature, if the schema of the feature as described in the previous sub-clause is available. This is independent of the feature encodings supported by the API.

9.8. GeoJSON

GeoJSON normatively supports WGS84 longitude/latitude, but the "prior arrangement" provision allows that other CRSs can be used if both client and server agree on the CRS. Clients that want to use a CRS that is not the default CRS have to state the CRS in the POST, PUT or PATCH request using the Content-Crs HTTP header to invoke the "prior arrangement" provision.

9.9. Geography Markup Language (GML)

This Standard does not specify an XML PATCH syntax / semantics that could be applied for GML feature updates. Two options are:

• use of the Update action from OGC Web Feature Service 2.0;
• use of RFC 5261 (An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors).

See OGC API - Features - Part 1: Core, Clause 10.

The media types for the CREATE, REPLACE and UPDATE requests as well as for the schema documents depend on the representations of the resources.

For GeoJSON features,

• CREATE and REPLACE operations will use application/geo+json,
• UPDATE operations will use application/merge-patch+json,
• schema documents will use application/schema+json.

For GML features,

• CREATE and REPLACE operations will use application/gml+xml,
• UPDATE operations will use application/xml,
• schema documents will use application/xml.

11. Security Considerations

See OGC API - Features - Part 1: Core, Clause 11.

Since CREATE, REPLACE, DELETE and UPDATE operations will change the resources and not "just" query them, servers will in almost all cases restrict the access to these operations.

Users making modifications to resources need to:

1. Be authenticated,
2. Have "modification privileges" on one or more of the resource collections offered by the API implementation instance and related endpoints,
3. Have access to one or more of the POST, PUT, PATCH and/or DELETE methods on the resources / resource endpoints.

The API definition must reflect this in the resource paths and their available methods.

The examples in the chapters specifying the requirements classes focus on the mechanics of the POST, PUT, DELETE, and PATCH methods and exclude authentication. Since authentication will typically be required for all requests, this section provides some examples/guidance:

The OpenAPI definition will declare the authentication schemes that the server supports for each operation (or for all operations supported by the server).

A member "security" in the OpenAPI definition object can be provided to list the default security schemes supported by all operations. Individual operations can override this default by providing a "security" member for the individual operation.

Example 1. Example OpenAPI definition with security requirements

The following OpenAPI definition declares that the API accepts either api keys in an "X-API-Key" header or JWT bearer tokens to authenticate the requestor. The server will decide, if an authenticated request is rejected or executed based on privileges of the authenticated user.

{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "My API",
    "description" : "This API ...",
    "version" : "1.0.0"
  },
  "servers" : [ {
    "url" : "https://example.com/api/v1"
  } ],
  "security" : [ {
    "JWT" : [ ],
    "api_key": [ ]
  } ],
  "paths" : { },
  "components" : {
    "securitySchemes": {
      "JWT" : {
        "type" : "http",
        "scheme" : "bearer",
        "bearerFormat" : "JWT"
      },
      "api_key" : {
        "type": "apiKey",
        "name": "X-API-Key",
        "in": "header"
      }
    }
  }
}

If the authentication of a secured request fails or if the user does not have sufficient privileges, the server will return an error.

In case the request does not include information to authenticate the user, the server will respond with a 401 response ("Unauthorized"). The response will include a "WWW-Authenticate" header with hints as to how to provide authentication credentials.

Unauthorized request

Client Server | | | DELETE /api/v1/collections/buildings/items/1234 HTTP/1.1 | | Host: example.com | |------------------------------------------------------------------>| | | | HTTP/1.1 401 Unauthorized | | Date: Mon, 23 May 2022 11🔞45 GMT | | WWW-Authenticate: Bearer realm="my-realm" | | WWW-Authenticate: ApiKey header="X-API-Key" | | Content-Type: application/problem+json | | Vary: Accept | | Content-Length: 86 | | | | { | | "status" : 401, | | "title" : "Unauthorized", | | "detail" : "HTTP 401 Unauthorized" | | } | |<------------------------------------------------------------------|

If valid authentication credentials have been provided, but the server refuses to execute the operation, because the user has insufficient privileges, the server will typically return a 403 response ("Forbidden").

Forbidden request

Client Server | | | DELETE /api/v1/collections/buildings/items/1234 HTTP/1.1 | | Host: example.com | | Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...7HgQ | |------------------------------------------------------------------>| | | | HTTP/1.1 403 Forbidden | | Date: Mon, 23 May 2022 11🔞55 GMT | | Content-Type: application/problem+json | | Vary: Accept | | Content-Length: 80 | | | | { | | "status" : 403, | | "title" : "Forbidden", | | "detail" : "HTTP 403 Forbidden" | | } | |<------------------------------------------------------------------|

However, for security reasons, the server may also decide to return other status codes to hide information from a potential attacker. For example, the server may decie to return a 401 response even for a valid, but un-privileged user. Or the server may return a 404 response ("Not Found") to hide the fact that the resource exists in the first place, typically if the user would also not be privileged to fetch the resource with a GET operation.

Annex A: Abstract Test Suite (Normative)

Annex B: Revision History

Annex C: Bibliography

• OpenAPI Initiative (OAI). OpenAPI Specification 3.0 [online]. 2020 [viewed 2020-03-16]. The latest patch version at the time of publication of this standard was 3.0.3, available at http://spec.openapis.org/oas/v3.0.3
• Open Geospatial Consortium (OGC). Welcome To The OGC APIs [online, viewed 2020-03-16]. Available at http://www.ogcapi.org/
• Open Geospatial Consortium (OGC). OGC API - Processes - Part 1: Core (Editor’s Draft) [online]. Edited by B. Pross. 2021 [viewed 2021-01-26]. Available at https://docs.ogc.org/DRAFTS/18-062.html
• Internet Engineering Task Force (IETF). RFC 5261: An Extensible Markup Language (XML) Patch Operations Framework Utilizing XML Path Language (XPath) Selectors [online]. Edited by J. Urpalainen. 2008 [viewed 2021-01-25]. Available at https://www.rfc-editor.org/rfc/rfc5261.html
• Internet Engineering Task Force (IETF). RFC 6585: Additional HTTP Status Codes [online]. Edited by M. Nottingham, R. Fielding. 2012 [viewed 2022-11-07]. Available at https://www.rfc-editor.org/rfc/rfc6585