OARec/STAC: add support for HTTP PATCH (#1171)

Author: tomkralidis

docs/transactions.rst

@@ -100,9 +100,12 @@ The below examples demonstrate transactional workflow using pycsw's OGC API - Re
    # insert GeoJSON metadata
    curl -v -H "Content-Type: application/geo+json" -XPOST http://localhost:8000/collections/metadata:main/items -d @foorecord.json
 
-   # update metadata
+   # update (full) metadata
    curl -v -H "Content-Type: application/geo+json" -XPUT http://localhost:8000/collections/metadata:main/items/foorecord -d @foorecord.json
 
+   # update (partial) metadata
+   curl -v -H "Content-Type: application/merge-patch+json" -XPATCH http://localhost:8000/collections/metadata:main/items/foorecord -d '{"properties": {"title": "newtitle"}}'
+
    # delete metadata
    curl -v -XDELETE http://localhost:8000/collections/metadata:main/items/foorecord
 
@@ -136,9 +139,12 @@ The below examples demonstrate transactional workflow using pycsw's OGC API - Re
    # insert STAC Item
    curl -v -H "Content-Type: application/json" -XPOST http://localhost:8000/stac/collections/metadata:main/items -d @fooitem.json
 
-   # update STAC Item
+   # update (full) STAC Item
    curl -v -H "Content-Type: application/json" -XPUT http://localhost:8000/stac/collections/metadata:main/items/fooitem -d @fooitem.json
 
+   # update (partial) STAC Item
+   curl -v -H "Content-Type: application/merge-patch+json" -XPATCH http://localhost:8000/stac/collections/metadata:main/items/fooitem -d '{"properties": {"title": "newtitle"}}'
+
    # delete STAC Item
    curl -v -XDELETE http://localhost:8000/stac/collections/metadata:main/items/fooitem
 
@@ -148,9 +154,12 @@ The below examples demonstrate transactional workflow using pycsw's OGC API - Re
    # insert STAC Collection
    curl -v -H "Content-Type: application/json" -XPOST http://localhost:8000/stac/collections -d @foocollection.json
 
-   # update STAC Collection
+   # update (full) STAC Collection
    curl -v -H "Content-Type: application/json" -XPUT http://localhost:8000/stac/collections/foocollection -d @foocollection.json
 
+   # update (partial) STAC Collection
+   curl -v -H "Content-Type: application/merge-patch+json" -XPATCH http://localhost:8000/stac/collections/foocollection -d '{"title": "newtitle"}'
+
    # delete STAC Collection
    curl -v -XDELETE http://localhost:8000/stac/collections/foocollection
 

pycsw/ogc/api/oapi.py

@@ -563,10 +563,10 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
         LOGGER.debug('Transactions enabled; adding put/delete')
 
         path['put'] = {
-            'summary': 'Updates Records items',
-            'description': 'Updates Records items',
+            'summary': 'Updates (full) Records items',
+            'description': 'Updates (full) Records items',
             'tags': ['metadata'],
-            'operationId': 'updateRecord',
+            'operationId': 'replaceRecord',
             'consumes': [
                 'application/geo+json', 'application/json', 'application/xml'
             ],
@@ -583,7 +583,38 @@ def gen_oapi(config, oapi_filepath, mode='ogcapi-records'):
                 {'$ref': '#/components/parameters/recordId'}
             ],
             'responses': {
-                '204': {'description': 'Successful update'},
+                '204': {'description': 'Successful update (full)'},
+                '400': {
+                    '$ref': '#/components/responses/InvalidParameter'
+                },
+                '500': {
+                    '$ref': '#/components/responses/ServerError'
+                }
+            }
+        }
+
+        path['patch'] = {
+            'summary': 'Updates (partial) Records items',
+            'description': 'Updates (partial) Records items',
+            'tags': ['metadata'],
+            'operationId': 'updateRecord',
+            'consumes': [
+                'application/geo+json', 'application/json', 'application/xml'
+            ],
+            'produces': ['application/json'],
+            'requestBody': {
+                'content': {
+                    'application/merge-patch+json': {
+                        'schema': {}
+                    }
+                }
+            },
+            'parameters': [
+                {'$ref': '#/components/parameters/collectionId'},
+                {'$ref': '#/components/parameters/recordId'}
+            ],
+            'responses': {
+                '204': {'description': 'Successful update (partial)'},
                 '400': {
                     '$ref': '#/components/responses/InvalidParameter'
                 },

pycsw/ogc/api/records.py

@@ -37,6 +37,7 @@
 from typing import List, Union
 from urllib.parse import urlencode, quote
 
+import json_merge_patch
 from owslib.ogcapi.records import Records
 from pygeofilter.parsers.ecql import parse as parse_ecql
 from pygeofilter.parsers.cql2_json import parse as parse_cql2_json
@@ -1015,7 +1016,7 @@ def item(self, headers_, args, collection, item):
     def manage_collection_item(self, headers_, action='create', collection=None,
                                item=None, data=None):
         """
-        :param action: action (create, update, delete)
+        :param action: action (create, replace, update, delete)
         :param collection: collection identifier
         :param item: record identifier
         :param data: raw data / payload
@@ -1028,13 +1029,13 @@ def manage_collection_item(self, headers_, action='create', collection=None,
                     405, headers_, 'InvalidParameterValue',
                     'transactions not allowed')
 
-        if action in ['create', 'update'] and data is None:
+        if action in ['create', 'replace', 'update'] and data is None:
             msg = 'No data found'
             LOGGER.error(msg)
             return self.get_exception(
                 400, headers_, 'InvalidParameterValue', msg)
 
-        if action in ['create', 'update']:
+        if action in ['create', 'replace']:
             try:
                 record = parse_record(self.context, data, self.repository)[0]
             except Exception as err:
@@ -1068,7 +1069,7 @@ def manage_collection_item(self, headers_, action='create', collection=None,
             code = 201
             response = {}
 
-        elif action == 'update':
+        elif action == 'replace':
             LOGGER.debug(f'Querying repository for item {item}')
             try:
                 _ = self.repository.query_ids([record.identifier])[0]
@@ -1082,6 +1083,40 @@ def manage_collection_item(self, headers_, action='create', collection=None,
             code = 204
             response = {}
 
+        elif action == 'update':
+            LOGGER.debug(f'Querying repository for item {item}')
+            try:
+                content = self.repository.query_ids([item])[0]
+            except Exception:
+                msg = 'Identifier does not exist'
+                LOGGER.debug(msg)
+                return self.get_exception(404, headers_, 'InvalidParameterValue', msg)
+
+            if 'id' in data:
+                msg = 'Update cannot alter id'
+                LOGGER.debug(msg)
+                return self.get_exception(400, headers_, 'InvalidParameterValue', msg)
+
+            content = json.loads(content.metadata)
+            record = json_merge_patch.merge(content, data)
+
+            try:
+                record = parse_record(self.context, record, self.repository)[0]
+            except Exception as err:
+                msg = f'Failed to parse data: {err}'
+                LOGGER.exception(msg)
+                return self.get_exception(400, headers_, 'InvalidParameterValue', msg)
+
+            if not hasattr(record, 'identifier'):
+                msg = 'Record requires an identifier'
+                LOGGER.exception(msg)
+                return self.get_exception(400, headers_, 'InvalidParameterValue', msg)
+
+            _ = self.repository.update(record)
+
+            code = 204
+            response = {}
+
         elif action == 'delete':
             constraint = {
                 'where': 'identifier = \'%s\'' % item,

pycsw/wsgi_flask.py

@@ -56,6 +56,7 @@
 
 BLUEPRINT.config = api_.config
 
+
 def get_api_type(urlpath):
     """
     Decorator to detect API type
@@ -157,8 +158,8 @@ def collections():
         return get_response(api_.collections(dict(request.headers), request.args))
 
 
-@BLUEPRINT.route('/collections/<collection>', methods=['GET', 'PUT', 'DELETE'])
-@BLUEPRINT.route('/stac/collections/<collection>', methods=['GET', 'PUT', 'DELETE'])
+@BLUEPRINT.route('/collections/<collection>', methods=['GET', 'PATCH', 'PUT', 'DELETE'])
+@BLUEPRINT.route('/stac/collections/<collection>', methods=['GET', 'PATCH', 'PUT', 'DELETE'])
 def collection(collection='metadata:main'):
     """
     OGC API collection endpoint
@@ -172,12 +173,17 @@ def collection(collection='metadata:main'):
         if request.method == 'PUT':
             return get_response(
                 stacapi.manage_collection_item(
-                    dict(request.headers), 'update', collection=collection,
+                    dict(request.headers), 'replace', collection=collection,
                     data=request.get_json(silent=True)))
         elif request.method == 'DELETE':
             return get_response(
                 stacapi.manage_collection_item(dict(request.headers),
                                                'delete', collection))
+        elif request.method == 'PATCH':
+            return get_response(
+                api_.manage_collection_item(dict(request.headers), 'update',
+                                            collection, item,
+                                            data=request.get_json(silent=True)))
         else:
             return get_response(stacapi.collection(dict(request.headers),
                                 request.args, collection))
@@ -281,9 +287,9 @@ def items(collection='metadata:main'):
 
 
 @BLUEPRINT.route('/collections/<collection>/items/<path:item>',
-                 methods=['GET', 'PUT', 'DELETE'])
+                 methods=['GET', 'PATCH', 'PUT', 'DELETE'])
 @BLUEPRINT.route('/stac/collections/<collection>/items/<item>',
-                 methods=['GET', 'PUT', 'DELETE'])
+                 methods=['GET', 'PATCH', 'PUT', 'DELETE'])
 def item(collection='metadata:main', item=None):
     """
     OGC API collection items endpoint
@@ -297,12 +303,17 @@ def item(collection='metadata:main', item=None):
     if request.method == 'PUT':
         return get_response(
             api_.manage_collection_item(
-                dict(request.headers), 'update', collection, item,
+                dict(request.headers), 'replace', collection, item,
                 data=request.get_json(silent=True)))
     elif request.method == 'DELETE':
         return get_response(
             api_.manage_collection_item(dict(request.headers), 'delete',
                                         collection, item))
+    elif request.method == 'PATCH':
+        return get_response(
+            api_.manage_collection_item(dict(request.headers), 'update',
+                                        collection, item,
+                                        data=request.get_json(silent=True)))
     else:
         if get_api_type(request.url_rule.rule) == 'stac-api':
             return get_response(stacapi.item(dict(request.headers), request.args,

requirements.txt

@@ -1,5 +1,6 @@
 click
 geolinks
+json_merge_patch
 legacy-cgi; python_version >= '3.13'
 lxml
 OWSLib

tests/functionaltests/suites/oarec/test_oarec_functional.py

@@ -4,7 +4,7 @@
 #          Angelos Tzotsos <gcpp.kalxas@gmail.com>
 #          Ricardo Garcia Silva <ricardo.garcia.silva@gmail.com>
 #
-# Copyright (c) 2025 Tom Kralidis
+# Copyright (c) 2026 Tom Kralidis
 # Copyright (c) 2022 Angelos Tzotsos
 # Copyright (c) 2023 Ricardo Garcia Silva
 #
@@ -341,11 +341,11 @@ def test_json_transaction(config, sample_record):
     element = e.find('{http://www.w3.org/2005/Atom}title').text
     assert element == 'title in English'
 
-    # update record
+    # update (full) record
     sample_record['properties']['title'] = 'new title'
 
     headers, status, content = api.manage_collection_item(
-        request_headers, 'update', item='record-123', data=sample_record)
+        request_headers, 'replace', item='record-123', data=sample_record)
 
     assert status == 204
 
@@ -355,6 +355,20 @@ def test_json_transaction(config, sample_record):
     assert content['id'] == 'record-123'
     assert content['properties']['title'] == 'new title'
 
+    # update (partial) record
+    data2 = {'properties': {'title': 'new title merge patch'}}
+
+    headers, status, content = api.manage_collection_item(
+        request_headers, 'update', item='record-123', data=data2)
+
+    assert status == 204
+
+    # test that record is in repository
+    content = json.loads(api.item({}, {}, 'metadata:main', 'record-123')[2])
+
+    assert content['id'] == 'record-123'
+    assert content['properties']['title'] == 'new title merge patch'
+
     # test XML representation
     params = {'f': 'xml'}
     content = api.item({}, params, 'metadata:main', 'record-123')[2]
@@ -365,7 +379,7 @@ def test_json_transaction(config, sample_record):
     assert element == 'record-123'
 
     element = e.find('{http://www.w3.org/2005/Atom}title').text
-    assert element == 'new title'
+    assert element == 'new title merge patch'
 
     # delete record
     headers, status, content = api.manage_collection_item(
@@ -455,7 +469,7 @@ def test_xml_transaction(config):
         b'Ut facilisis justo ut lacus', b'new title')
 
     headers, status, content = api.manage_collection_item(
-        request_headers, 'update', item='record-456', data=test_data_xml)
+        request_headers, 'replace', item='record-456', data=test_data_xml)
 
     assert status == 204
 

tests/functionaltests/suites/stac_api/test_stac_api_functional.py

@@ -902,7 +902,7 @@ def test_json_transaction(config, sample_collection, sample_item,
     sample_item['properties']['datetime'] = '2021-12-14T22:38:32Z'
 
     headers, status, content = api.manage_collection_item(
-        request_headers, 'update', item='20201211_223832_CS2',
+        request_headers, 'replace', item='20201211_223832_CS2',
         data=sample_item, collection='metadata:main')
 
     assert status == 204
@@ -994,11 +994,11 @@ def test_json_transaction(config, sample_collection, sample_item,
 
     assert content['numberMatched'] == 0
 
-    # update collection
+    # update (full) collection
     sample_collection['title'] = 'test title update'
 
     headers, status, content = api.manage_collection_item(
-        request_headers, 'update', item=collection_id,
+        request_headers, 'replace', item=collection_id,
         data=sample_collection, collection='metadata:main')
 
     assert status == 204
@@ -1010,6 +1010,22 @@ def test_json_transaction(config, sample_collection, sample_item,
 
     assert content['title'] == sample_collection['title']
 
+    # update (partial) collection
+    data2 = {'title': 'test title update merge patch'}
+
+    headers, status, content = api.manage_collection_item(
+        request_headers, 'update', item=collection_id,
+        data=data2, collection='metadata:main')
+
+    assert status == 204
+
+    headers, status, content = api.collection(
+        {}, {'f': 'json'}, collection=collection_id)
+
+    content = json.loads(content)
+
+    assert content['title'] == 'test title update merge patch'
+
     # test that item is in repository
     content = json.loads(api.item({}, {}, 'metadata:main',
                          '20201211_223832_CS2')[2])