Follow REST norms for updating package definitions via the API (Versioning system Option 2)

[markboots]

The current spec uses POST to /flow-results/packages both to create an initial package definition, and to create a new version of a package (when observing Option 2 for versioning). In the latter case, it posts a package with an existing id but a new modified.

This deviates from REST norms that would use POST for create and PUT for updates to a defined URL.

The JSONApi requirement defined in Updating Resources (http://jsonapi.org/format/#crud-updating) is to use PATCH for updates.

Proposal:

Adhere to JSONApi by introducing a new endpoint:

PATCH /flow-results/packages/{uuid}

for updating a package definition with a new version.

@ukanga @nditada thoughts?

[nditada]

👍 on PATCH for updates.

[ukanga]

:+1: on PATCH

[markboots]

Agreed on the call today:

• PATCH (for compliance with JSONApi), and
• additionally require for Flow Results that the whole package is sent [not just the changed fields in the package]

Ona expects to receive the whole package.

See example for JSONApi patch here:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "packages",
    "id": "[id]",
    "attributes": {
      // full package goes here
    }
  }
}```

[markboots]

[Ona production update earliest Wednesday]

[ukanga]

@markboots just confirmed that PATCH will work in the current Ona production, we have the support already.

[markboots]

Awesome, thanks for the update!

[jory-viamo]

Successfully POSTed then PATCHed an update to Ona. Looks great!