Patch endpoints

[rhysrevans3]

Description:
Adds PATCH endpoints to transaction extension. Adds support for RFC 6902 and RFC 7396. Pivots on header Content-Type value.

Related pull request: stac-api-extensions/transaction#14

PR Checklist:

• pre-commit hooks pass locally
• Tests pass (run make test)
• Documentation has been updated to reflect changes, if applicable, and docs build successfully (run make docs)
• Changes are added to the CHANGELOG.

[rhysrevans3]

I've had to switch from stac-pydantic Item/Collection to Dict to allow for partial updates. Not sure if this is the best method or if you can switch off pydantic validation. Another option would be having separate models for partial items/collections in stac-pydantic where all attributes.

[vincentsarago]

I've had to switch from stac-pydantic Item/Collection to Dict to allow for partial updates. Not sure if this is the best method or if you can switch off pydantic validation. Another option would be having separate models for partial items/collections in stac-pydantic where all attributes.

Would a typedDict make more sense?

[vincentsarago]

@rhysrevans3 should we wait for stac-api-extensions/transaction#14 to be merged/published?

[vincentsarago]

because we're using pydantic model I think we can use Field

class PatchMoveCopy(BaseModel):
   """Move or Copy Operation."""

   path: str
   op: Literal["move", "copy"]
   fromurl: str = Field(alias="from")

but then the attribute is .fromurl not .from

[rhysrevans3]

Ah I hadn't seen alias before that looks neater.

I've also added:

model_config = ConfigDict(populate_by_name=True)

which means you can do this:

patch_operation = PatchMoveCopy(**{"path": "hello", "from":"world", "op": "move"})

And overrode the model_dump method so by_alias defaults to True to use the alias in the model dump

patch_operation.model_dump()
#> {'path': 'hello', 'op': 'move', 'from': 'world'}

Not sure if this is the right thing to do or if we should expect people to use:

patch_operation.model_dump(by_alias=True)

[vincentsarago]

@rhysrevans3 I'm trying to get a general sense of the patch operation. It's not clear to me what are the requirements that an API should implement. By default it seems that a client will have to support a lot of things

For example, I'm looking at https://docs.ogc.org/DRAFTS/20-002.html#update_clause and I don't see reference to the move/copy operations

[rhysrevans3]

My understanding is RFC 5789, which the OGC doc references, say a PATCH endpoint should except a set of actions to modify the requested resource. But it doesn't specify what these actions should be.

RFC 6902 extends this and specify a set of allowed operations (add, remove, replace, move, copy, test) which is what I have suggested in stac-api-extensions/transaction#14.

Currently the README on the transaction extension suggests the PATCH endpoint follows RFC 7396 which accepts a partial json document which it merges with the existing document this might not be the best choice for STAC because of it's handling of null values. As mentioned in this issue stac-api-extensions/transaction#13

[djspstfc]

Just to add to @rhysrevans3 's comments, the main issue with supporting only RFC7396 (or RFC7386) is the "magic" behaviour of setting attribute to null in combination with the elastic search backend:

• RFC7396 treats explicit null as a command to delete that attribute (this is your "delete" patch command)
• If you actually want to set a value to null, you can't
• ElasticSearch on the other hand, has a different understanding of explicit null as "leave this in the document but don't index this value"

Without a fairly complicated scripting command on elastic search, it would not be possible for elastic search to return a _source document that meets the expected result of an explicit null being sent in a PATCH request.

RFC6902 gets around this by allowing you to explicitly say "that attribute there, delete it" and not "that attribute there, I'm going to tell you to set it to null but which I mean please write a script to tell elastic search to remove it from the source document and reindex".

[vincentsarago]

@rhysrevans3 The overall looks great, just added one comment about using stac-pydantic base model.

As I've asked couple weeks ago, should we wait for stac-api-extensions/transaction#14 to be merged? do you know anyone who could help move this PR forward?

[rhysrevans3]

@rhysrevans3 The overall looks great, just added one comment about using stac-pydantic base model.

As I've asked couple weeks ago, should we wait for stac-api-extensions/transaction#14 to be merged? do you know anyone who could help move this PR forward?

Ideally yes I think it would be better to have that PR merged first.

But my understanding is that RFC 6902 and RFC 7396 are implementations of RFC 5789, which is the current STAC/OGC specification. So this merging this pull still keeps within the current STAC specification.

But given @m-mohr comments on that pull request maybe it's best to wait for OGC's opinion.

[m-mohr]

Did someone open an issue with OGC API - Features? (If yes, where?) Otherwise you may wait forever ;)

[rhysrevans3]

Sorry I've been at a conference/on leave I've created a new issue here

[m-mohr]

@rhysrevans3 Thanks.

Given the response in opengeospatial/ogcapi-features#957, we may also want to open an issue in the Transaction extension itself so that we can reflect the updated to OGC API - Features in the extension, too. Would you mind opening that issue, too? (I also just returned from four weeks of travelling today.)

[rhysrevans3]

@m-mohr There is an issue stac-api-extensions/transaction#13 and a pull request stac-api-extensions/transaction#14 on the transaction extension repo. :)

[m-mohr]

Oh cool, too many repos to monitor. Left my comment(s) there.