Open Geospatial Consortium |
Submission Date: <yyyy-mm-dd> |
Approval Date: <yyyy-mm-dd> |
Publication Date: <yyyy-mm-dd> |
External identifier of this OGC® document: http://www.opengis.net/doc/IS/ogcapi-features-4/1.0 |
Internal reference number of this OGC® document: 20-002r1 |
Version: 1.0.0-draft.2 |
Latest Published Draft: n/a |
Category: OGC® Implementation Standard |
Editors: Panagiotis (Peter) A. Vretanos, Clemens Portele |
OGC API - Features - Part 4: Create, Replace, Update and Delete |
Copyright notice |
Copyright © 2024 Open Geospatial Consortium |
To obtain additional rights of use, visit http://www.opengeospatial.org/legal/ |
Warning |
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.
Document type: OGC® Standard |
Document subtype: Interface |
Document stage: Draft |
Document language: English |
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.
- 1. Scope
- 2. Conformance
- 3. References
- 4. Terms, definitions and abbreviated terms
- 5. Conventions and background
- 6. Requirements Class "Create/Replace/Delete"
- 7. Requirements Class "Update"
- 8. Requirements Class "Optimistic Locking"
- 9. Requirements Class "Features"
- 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.
|
Note
|
This Standard was developed in the Features API SWG but is being written as a generic extension that is applicable to a variety of resource types including features. The feature-specific portions of this extension are isolated to the clause titled Features. It is anticipated that the bulk of this extension will eventually be moved into 'OGC API - Common' and only the feature-specific content will remain to be managed by the Features API SWG. |
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:
Name |
Affiliation |
Clemens Portele (editor) |
interactive instruments GmbH |
Panagiotis (Peter) A. Vretanos (editor) |
CubeWerx Inc. |
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.
|
Note
|
Additional OGC Standards are planned to handle transactions that require batch or atomicity semantics. |
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.
| Resource endpoint | HTTP method | |||
|---|---|---|---|---|
POST |
PUT |
PATCH |
DELETE |
|
|
n/a |
n/a |
n/a |
|
|
n/a |
|||
The option to create a new resource with PUT is conditional and depends on the characteristics of the collection.
2. Conformance
This Standard defines five requirements / conformance classes:
The standardization target type is "Web APIs".
The URIs of the associated conformance classes are:
| Conformance class | URI |
|---|---|
Create/Replace/Delete |
http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/create-replace-delete |
Update |
http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/update |
Optimistic Locking using Timestamps |
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/optimistic-locking-timestamps |
Optimistic Locking using ETags |
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/optimistic-locking-etags |
Features |
http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/features |
Conformance with this Standard shall be checked using all the relevant tests specified in Annex A of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
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
|
Note
|
This is accomplished by a server providing HTTP validator fields describing the state of a resource and evualting preconditions submitted by clients about the current state of a resource that the client wants to change. See RFC 9110 (HTTP Semantics), section 8.8. If the validator in a client request does not match the state of the resource on the server, the operation fails and the client must re-fetch the resource and retry the update operation based on the new state. |
5. Conventions and background
5.1. General remarks
See OGC API - Features - Part 1: Core, Clauses 5 and 6.
5.2. Identifiers
The normative provisions in this Standard are denoted by the URI http://www.opengis.net/spec/ogcapi-features-4/1.0.
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
Requirements Class |
|
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/create-replace-delete |
|
Target type |
Web API |
Dependency |
|
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
|
The use of the HTTP PATCH method is not defined in this requirements class. The Update requirements class defines the use of the HTTP PATCH method. |
|
Note
|
In order to promote interoperability, each OGC Standard that extends this Standard should make recommendations concerning the representation of resources. See Features for a discussion of feature representations. |
Requirement 1 |
/req/core/methods |
A |
A server SHALL implement one or more of the methods HTTP POST, PUT and/or DELETE for each mutable resource. |
B |
A server SHALL declare which methods are supported for each resource via the HTTP OPTIONS method. |
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.
More specific guidance is provided for each resource, where applicable.
Permission 1 |
/per/core/additional-status-codes |
A |
Servers may support other capabilities of the HTTP protocol and therefore may return other status codes than those listed in Table 3. |
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
See OGC API - Features - Part 1: Core, section Support for cross-origin requests, about the importance of supporting cross-origin requests, typically via Cross-origin resource sharing (CORS).
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 <resources endpoint> HTTP/1.1 |
| Content-Type: <media type of resource representation> |
| |
| ... Body contains representation of the resource ... |
|-------------------------------------------------------------->|
| |
| HTTP/1.1 201 Created |
| Location: <resource endpoint> |
|<--------------------------------------------------------------|
6.2.2. Operation
Requirement 2 |
/req/create-replace-delete/post-op |
Condition |
Server declares support for the POST method on the resources endpoint via the |
A |
The server SHALL support the HTTP POST operation at the resources endpoint. |
6.2.3. Request body
6.2.3.1. Overview
Requirement 3 |
/req/create-replace-delete/post-body |
A |
The body of a POST request SHALL contain a representation of the resource to be added to the specified collection. |
Permission 2 |
/per/create-replace-delete/insert-body |
A |
A server MAY support any resource encoding in the body of a HTTP POST operation. |
Requirement 4 |
/req/create-replace-delete/post-content-type |
A |
A |
See section 8.3 of RFC 9110 for details.
6.2.4. Response
Requirement 5 |
/req/create-replace-delete/post-response-rid |
A |
If the operation completes successfully, the server SHALL assign a new, unique identifier within the collection for the newly added resource. |
Permission 3 |
/per/create-replace-delete/rid |
A |
If the representation of the resource submitted in the request body contained a resource identifier, the server MAY use this identifier as the new resource identifier in the collection or the server MAY ignore the value and assign its own identifier for the resource. |
Requirement 6 |
/req/create-replace-delete/post-response |
A |
A successful execution of the operation SHALL be reported as a response with a HTTP status code |
B |
A response with HTTP status code |
C |
If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code |
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.
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.
|
Note
|
The new content replaces the old content of the resource. Version control is not discussed in this Standard. |
Client Server
| |
| PUT <resource endpoint> HTTP/1.1 |
| Content-Type: <media type of updated resource representation> |
| |
| ... Body contains representation of new resource content ... |
|---------------------------------------------------------------->|
| |
| HTTP/1.1 204 OK |
|<----------------------------------------------------------------|
6.3.2. Operation
Requirement 7 |
/req/create-replace-delete/put-op |
Condition |
Server declares support for the PUT method on the resources endpoint via the |
A |
For every resource in the collection, the server SHALL support the HTTP PUT operation. |
Permission 4 |
/per/create-replace-delete/put-create |
A |
A server MAY support the PUT method on a non-existing resource. |
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.4. Overview
Requirement 8 |
/req/create-replace-delete/put-body |
A |
The body of the PUT request SHALL contain a representation of the new resource content. |
Permission 5 |
/per/create-replace-delete/update-put-body |
A |
A server MAY support any resource encoding in the body of a HTTP PUT operation. |
Requirement 9 |
/req/create-replace-delete/put-content-type |
A |
The |
See section 8.3 of RFC 9110 for details.
6.3.5. Response
Requirement 10 |
/req/create-replace-delete/put-response |
A |
A successful execution of the operation SHALL be reported as a response with a HTTP status code |
B |
If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code |
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.
Requirement 11 |
/req/create-replace-delete/put-rid |
A |
If the representation of the resource submitted in the request body contained a resource identifier, the server SHALL ignore this identifier. |
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).
Requirement 12 |
/req/create-replace-delete/put-rid-exception |
A |
If the target resource does not exist and the server does not support creating new resources using PUT, the server SHALL indicate an unsuccessful execution of the operation with a HTTP status code |
B |
If the request includes an |
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.
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 <resource endpoint> HTTP/1.1 |
+-------------------------------------------------------------->|
| |
| HTTP/1.1 204 OK |
+<--------------------------------------------------------------|
6.4.2. Operation
Requirement 13 |
/req/create-replace-delete/delete-op |
Condition |
Server declares support for the DELETE method on the resources endpoint via the |
A |
For every resource in the collection, the server SHALL support the HTTP DELETE operation. |
6.4.3. Response
Requirement 14 |
/req/create-replace-delete/delete-response |
A |
A successful execution of the operation SHALL be reported as a response with a HTTP status code |
B |
If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code |
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.
Recommendation 1 |
/rec/delete/no-feature |
A |
If no resource with the identifier exists in the collection, the response SHOULD be |
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.
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 <resource endpoint> HTTP/1.1 |
+-------------------------------------------------------------->|
| |
| HTTP/1.1 200 OK |
| Allow: <list of relevant HTTP methods> |
+<--------------------------------------------------------------|
6.5.3. Operation
Requirement 15 |
/req/create-replace-delete/options-op |
A |
The server SHALL support the HTTP OPTIONS operation at each resource endpoint. |
6.5.4. Request body
Permission 6 |
/per/create-replace-delete/options/req-body |
A |
Content MAY be included in the body of the HTTP OPTIONS operation. The format for such a body is not defined in this Standard. |
B |
Servers MAY discard the request body. |
6.5.5. Response
Requirement 16 |
/req/create-replace-delete/options-response |
A |
A successful execution of the operation SHALL be reported as a response with a HTTP status code |
B |
A response with HTTP status code |
C |
The value of the |
Permission 7 |
/per/options/other-methods |
A |
Although this Standard only deals with the HTTP POST, PUT, PATCH and DELETE methods, any other relevant HTTP method MAY be specified as the value of the |
Permission 8 |
/per/create-replace-delete/options/res-body |
A |
The response body on an HTTP OPTIONS operation MAY include content but the format for such a body is not defined in this Standard. |
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.
Client Server
| |
| OPTIONS /collections/oakland_buildings/items HTTP/1.1 |
|------------------------------------------------------------------>|
| |
| HTTP/1.1 200 OK |
| Allow: GET, HEAD, POST |
|<------------------------------------------------------------------|
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
Requirements Class |
|
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/update |
|
Target type |
Web API |
Dependency |
|
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.
Requirement 17 |
/req/update/methods |
A |
A server SHALL declare support for the HTTP PATCH method via the HTTP OPTIONS method. |
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 <resource endpoint> HTTP/1.1 |
| Content-Type: <media type of body> |
| |
| ... Body contains a document describing the changes to make |
| to parts of the specified resource ... |
|-------------------------------------------------------------->|
| |
| HTTP/1.1 204 OK |
|<--------------------------------------------------------------|
7.2.2. Operation
Requirement 18 |
/req/update/update-patch-op |
A |
For every resource in a collection, the server SHALL support the HTTP PATCH operation. |
7.2.3. Request body
Requirement 19 |
/req/update/update-patch-body |
A |
The request body SHALL contain a document describing the specific parts of the target resource that should be modified by the operation. |
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
Requirement 20 |
/req/update/update-patch-response |
A |
A successful execution of the operation SHALL be reported as a response with a HTTP status code |
B |
If the operation is not executed immediately, but is added to a processing queue, the response SHALL have a HTTP status code |
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.
Requirement 21 |
/req/update/rid |
A |
If the representation of the updated resource submitted in the request body contained a resource identifier, the server SHALL ignore this identifier. |
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.
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:
Recommendation 2 |
/rec/create-replace-delete/update/schema If a server imposes schema constraints on resources that if offers then it SHOULD publish a schema as described in OGC API - Features - Part 5: Schemas. |
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.
|
Note
|
The request and response payloads are intentionally omitted in the example to highlight the HTTP header interactions between the server and the clients. |
|
Note
|
Some names in this example are contracted using ellipses to save space. |
|
Note
|
The alphabetic letters delimited using [] are time instants and correspond to the time instants in Table 4
|
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]
| Time Instance | Description |
|---|---|
A |
Client A issues a GET to retrieve feature |
B |
Client B issues a GET to retrieve the same feature |
C |
The server responds to Client B. The response includes entity tag (Etag) |
D |
The server responds to Client A. The response also includes ETag |
E |
Client A modifies its local copy of |
F |
The server successfully processes Client A’s request. The server generates a new ETag |
G |
Client B, unaware of Client A’s changes, modifies its (now outdated) local copy of |
H |
The server successfully processes Client B’s request and Client A’s change is silently lost. Once again, since the stage of the resource has changed, the server generates a new ETag |
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-Modifiedfield is the date and time at which the server believes the selected representation was last modified. -
The
ETagfield 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.
|
Note
|
It is still useful to provide weak ETag headers, because for other conditional requests weak ETag validation is sufficient. For example, for If-None-Match headers weak validation is used. I.e., the use of weak ETags is sufficient to support 304 status responses (Not Modified) on GET requests to resources.
|
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.1. Overview
Requirements Class |
|
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/optimistic-locking-timestamps |
|
Target type |
Web API |
A server that implements this requirements class generates a Last-Modified header when the resource is fetched or modified representing the last time the resource was changed and recognizes the If-Unmodified-Since conditional HTTP header in order to implement optimistic locking of resources to support concurrency.
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.
Requirement 22 |
/req/optimistic-locking-timestamps/get-last-modified-response |
A |
The response to a HTTP GET operation used to retrieve a representation of a resource SHALL include a |
Requirement 23 |
/req/optimistic-locking-timestamps/put-last-modified-response |
A |
A resource successfully replaced by a HTTP PUT operation SHALL include a |
Requirement 24 |
/req/optimistic-locking-timestamps/patch-last-modified-response |
Condition |
Server implements the Update conformance class. |
A |
A resource successfully updated by a HTTP PATCH operation SHALL include a |
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-Modifiedheader 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.
Requirement 25 |
/req/optimistic-locking-timestamps/ifunmodifiedsince-put-op |
A |
A HTTP PUT operation that replaces a resource SHALL include an |
Requirement 26 |
/req/optimistic-locking-timestamps/ifmatch-put-eval |
A |
The value of an |
Requirement 27 |
/req/optimistic-locking-timestamps/ifunmodifiedsince-patch-op |
Condition |
Server implements the Update conformance class. |
A |
A HTTP PUT operation that updates a resource SHALL include an |
Requirement 28 |
/req/optimistic-locking-timestamps/ifunmodifiedsince-patch-eval |
Condition |
Server implements the Update conformance class. |
A |
The value of an |
Permission 9 |
/per/optimistic-locking-timestamps/ifunmodifiedsince-missing |
Condition |
The |
A |
The server MAY respond with a HTTP status code of 428 (Precondition required), as specified in RFC 6585: Additional HTTP Status Codes, or 409 (Conflict). |
B |
Alternatively, the server MAY execute the operation and return a HTTP status code in the 2xx range. |
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.
|
Note
|
The request and response payload are intentionally omitted in the example to highlight the HTTP header interactions between the server and the clients. |
|
Note
|
Some names in the example are contracted using ellipses to save space. |
|
Note
|
The alphabetic letters delimited using [] are time instants and correspond to the time instants in Table 5
|
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]
| Time Instance | Description |
|---|---|
A |
Client A issues a GET to retrieve the feature with identifier |
B |
Client B issues a GET to retrieve the same feature, |
C |
The server responds to Client B. The response includes |
D |
The server responds to Client A. The response also includes |
E |
Client A modifies its local copy of |
F |
Since the resource has not changes since the timestamp specified by the |
G |
Client B, unaware of Client A’s changes, modifies its local copy of |
H |
The server evaluates the |
I |
The Client B re-fetches the resource to obtain its current state. |
J |
The server responds and includes |
K |
Client B once again modifies its local copy of |
L |
Since the resource has not changed since the specified timestamp — indicating the Client B’s understanding of the state of the resource is current — the server successfully processes Client B’s request. A new |
8.3. Optimistic locking with ETags
8.3.1. Overview
Requirements Class |
|
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/optimistic-locking-etags |
|
Target type |
Web API |
A server that implements this requirements class generates an entity tag representing the state of the resource when the resource is fetched or modified and recognizes the If-Match conditional HTTP header in order to implement optimistic locking of resources to support concurrency.
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.
Requirement 29 |
/req/optimistic-locking-etags/get-etag-response |
A |
The response to a HTTP GET operation used to retrieve a representation of a resource SHALL include an |
Requirement 30 |
/req/optimistic-locking-etags/put-etag-response |
A |
A resource successfully replaced by a HTTP PUT operation SHALL include an |
Requirement 31 |
/req/optimistic-locking-etags/patch-etag-response |
Condition |
Server implements the Update conformance class. |
A |
A resource successfully updated by a HTTP PATCH operation SHALL include an |
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.
Requirement 32 |
/req/optimistic-locking-etags/ifmatch-put-op |
A |
A HTTP PUT operation that replaces a resource SHALL include an |
Requirement 33 |
/req/optimistic-locking-etags/ifmatch-put-eval |
A |
The value of an |
Requirement 34 |
/req/optimistic-locking-etags/ifmatch-patch-op |
Condition |
Server implements the Update conformance class. |
A |
A HTTP PUT operation that updates a resource SHALL include an |
Requirement 35 |
/req/optimistic-locking-etags/ifmatch-patch-eval |
Condition |
Server implements the Update conformance class. |
A |
The value of an |
Permission 10 |
/per/optimistic-locking-etags/ifmatch-patch-op |
Condition |
The |
A |
The server MAY respond with a HTTP status code of 428 (Precondition required), as specified in RFC 6585, or 409 (Conflict). |
B |
Alternatively, the server MAY execute the operation and return a HTTP status code in the 2xx range. |
Permission 11 |
/per/optimistic-locking-etags/ifmatch-star |
A |
A server MAY support the value |
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.
|
Note
|
The request and response payload are intentionally omitted in the example to highlight the HTTP header interactions between the server and the clients. |
|
Note
|
Some names in the example are contracted using ellipses to save space. |
|
Note
|
The alphabetic letters delimited using [] are time instants and correspond to the time instants in Table 6
|
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]
| Time Instance | Description |
|---|---|
A |
Client A issues a GET to retrieve the feature with identifier |
B |
Client B issues a GET to retrieve the same feature, |
C |
The server responds to Client B. The response includes |
D |
The server responds to Client A. The response also includes |
E |
Client A modifies its local copy of |
F |
Since the value of the client-provided |
G |
Client B, unaware of Client A’s changes, modifies its local copy of |
H |
The server evaluates the |
I |
The Client B re-fetches the resource to obtain its current state. |
J |
The server responds and includes |
K |
Client B once again modifies its local copy of |
L |
Since the value of the client-provided |
8.4. Exceptions
See HTTP status codes.
9. Requirements Class "Features"
9.1. Overview
Requirements Class |
|
http://www.opengis.net/spec/ogcapi-features-4/1.0/req/features |
|
Target type |
Web API |
Dependency |
|
Dependency |
OGC API - Features - Part 1: Core, Requirements Class "Core" |
Conditional Dependency |
OGC API - Features - Part 1: Core, Requirements Class "GeoJSON" |
Conditional Dependency |
|
Conditional Dependency |
|
Conditional Dependency |
|
Conditional Dependency |
|
Conditional Dependency |
OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
Conditional Dependency |
OGC API - Features - Part 5: Schemas, Requirements Class "Returnables and Receivables" |
This clause defines requirements for the case when the resource type is a feature.
9.2. Resources endpoint
Requirement 36 |
/req/features/resources-endpoint |
A |
For features, the resources endpoints SHALL be URIs specified by the URI template |
B |
The parameter |
C |
The parameter |
9.3. Resource endpoint
Requirement 37 |
/req/features/resource-endpoint |
A |
For features, the resource endpoints SHALL be URIs specified by the URI template |
B |
The parameter |
C |
The parameter |
D |
The parameter |
9.4. Support for creating features using the PUT method
Requirement 38 |
/req/features/collection-endpoint |
A |
If the server supports creating new features for a collection |
B |
The parameter |
C |
The parameter |
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.
Requirement 39 |
/req/features/crs-crs84 |
Condition |
Server does not implement OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
A |
The server SHALL interpret all geometries in request bodies of requests to the resources or resource endpoints to be in the coordinate reference system http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS 84 longitude/latitude) for geometries without height information and http://www.opengis.net/def/crs/OGC/0/CRS84h (WGS 84 longitude/latitude plus ellipsoidal height) for geometries with height information. |
B |
If the request declares that the coordinates are in a different coordinate reference system (e.g., by using the |
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.
Requirement 40 |
/req/features/content-crs-header |
Condition |
Server implements OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
A |
The server SHALL inspect CREATE, REPLACE and UPDATE requests for the |
Requirement 41 |
/req/features/default-crs |
Condition |
Server implements OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
Condition |
The request does not declare that coordinates are in a specific coordinate reference system (by using the |
A |
The server SHALL interpret all geometries in request bodies of requests to the resources or resource endpoints to be in the coordinate reference system http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS 84 longitude/latitude) for geometries without height information and http://www.opengis.net/def/crs/OGC/0/CRS84h (WGS 84 longitude/latitude plus ellipsoidal height) for geometries with height information. |
Requirement 42 |
/req/features/crs-other-crs |
Condition |
Server implements OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
Condition |
The request declares that coordinates are in a specific coordinate reference system (by using the |
A |
The server SHALL interpret all geometries in request bodies of requests to the resources or resource endpoints to be in the coordinate reference system declared in the request. |
B |
If the server does not support the coordinate reference system declared in the request for the feature collection, the server SHALL return an error. |
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.
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.
Recommendation 3 |
/rec/features/crs-storage-crs |
Condition |
Server implements OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
A |
The server SHOULD declare the |
B |
The server SHOULD support all CRSs that are declared in the |
C |
The server MAY only support the storage CRS in CREATE, REPLACE or UPDATE requests to avoid coordinate conversion in mutations of feature resources. |
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.
Requirement 43 |
/req/features/schema |
Condition |
|
A |
The response content of a GET request to |
B |
The server SHALL accept mutation requests where each feature property in the request meets the schema constraints of the corresponding, receivable property in the JSON Schema. |
C |
Unless the JSON Schema includes a statement |
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
idmember 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.
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.
Requirement 44 |
/req/features/update-json-merge-patch |
Condition |
Server implements Requirements Class "Update" |
Condition |
|
Condition |
Server advertises support for media type |
A |
The server SHALL process PATCH requests with a content type |
B |
The server SHALL reject requests where the property with |
C |
The server SHALL process requests that update a spatial property under the assumption that the value is a GeoJSON geometry object. |
D |
The server SHALL unset properties that have the value |
9.8. GeoJSON
Requirement 45 |
/req/features/geojson-create-replace |
Condition |
Server implements OGC API - Features - Part 1: Core, Requirements Class "GeoJSON" |
Condition |
Server advertises support for media type |
Condition |
|
A |
In a REPLACE operation, the server SHALL ignore an "id" member in the request or, alternatively, reject the request, if the "id" value differs from the |
B |
The value of the "geometry" member SHALL be mapped to the property with the role "primary-geometry". |
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)
Requirement 46 |
/req/features/gml-create-replace |
Condition |
|
Condition |
Server advertises support for media type |
A |
In a REPLACE operation, the server SHALL ignore a |
Requirement 47 |
/req/features/gml-srsname |
Condition |
Server implements OGC API - Features - Part 2: Coordinate Reference Systems by Reference |
Condition |
A CREATE, REPLACE and UPDATE request has been submitted with a |
A |
The server SHALL inspect the |
B |
A |
This Standard does not specify an XML PATCH syntax / semantics that could be applied for GML feature updates. Two options are:
10. Media Types
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:
-
Be authenticated,
-
Have "modification privileges" on one or more of the resource collections offered by the API implementation instance and related endpoints,
-
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.
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.
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:18: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").
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:18: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)
|
Note
|
Conformance classes and test cases for all requirements classes and requirements will be added once the requirements classes and requirements are final. |
Annex B: Revision History
| Date | Release | Editor | Primary clauses modified | Description |
|---|---|---|---|---|
2020-02-17 |
1.0.0-SNAPSHOT |
P. Vretanos |
all |
initial version |
2020-06-02 |
1.0.0-SNAPSHOT |
P. Vretanos |
all |
reorganize to separate feature-specific aspects in its own requirements class |
2024-03-07 |
1.0.0-draft.1 |
P. Vretanos, C. Portele |
all |
draft for OAB review |
2024-06-04 |
1.0.0-draft.2 |
P. Vretanos, C. Portele |
all |
draft for Public Comment |
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