JSON Patch

The Limecraft Flow API supports HTTP PATCH on some (most) of its resources. This allows updating certain properties of a resource without changing the other properties of that resource.

Limecraft Flow API’s PATCH follows rfc6902 (see also https://jsonpatch.com/), but with one extension. We also support a create operation, which behaves similar to add but fails if a value is already present at the path.

The following example sets the clipMetadata.flipHorizontal field to true, and sets the description field as well.

[
    {
        'op': 'add',
        'path': '/clipMetadata/flipHorizontal',
        'value': true
    },
    {
        'op': 'add',
        'path': '/description',
        'value': 'my description'
    }
]

Note that a single PATCH action contains a list of operations, which are executed in order. If one of these fails, the entire PATCH action is rolled back (this is part of the spec).

Pitfall: parent must exist

A common PATCH pitfall is that the "parent path" must exist before changing it.

[
    {
        'op': 'add',
        'path': '/structuredDescription/someThing/subproperty',
        'value': 'my value'
    }
]

The above PATCH will fail if /structuredDescription/someThing does not already exist.

Overwriting

Note that the PATCH will silently set the property, even if someone else changed it just before that.

  • description is "my initial description"

  • userA and userB load a page which shows that "my initial description"

  • userA changes the description from "my initial description" to "user A was here" and saves it

[
    {
        'op': 'add',
        'path': '/description',
        'value': 'user A was here'
    }
]

  • userB changes the description from "my initial description" (in the UI) to "user B was here" and saves it

[
    {
        'op': 'add',
        'path': '/description',
        'value': 'user B was here'
    }
]

Depending on who saved last, the result will be "user A was here" (if A saved last) or "user B was here" (if B saved last). Neither of the users will know that they overwritten something of the other user.

If this behaviour is a problem, one can add test ops to the PATCH, which verify the description is "my initial description" before attempting to change it using add.

[
    {
        'op': 'test',
        'path': '/description',
        'value': 'my initial description'
    },
    {
        'op': 'add',
        'path': '/description',
        'value': 'user A was here'
    }
]