Collection+JSON Extensions.md

Collection+JSON Extensions

1.0 Command Templates

Clients that support the Collection+JSON media type MAY be able to recognize and parse command templates found within responses. Command templates MAY consist of a data array associated with an href property. The commands arrary supports command templates.

For command templates, the name/value pairs of the data array set are sent as JSON in the body ({"id": 1, "members_to_notify": "all"}) or multipart/form-data, both via an HTTP POST.

2.0 commands

The commands array is an OPTIONAL top-level property of the Collection+JSON document.

The commands array SHOULD contain one or more anonymous objects. Each object composed of five possible properties: href (REQUIRED), rel (REQUIRED), name (OPTIONAL), prompt (OPTIONAL), and a data array (OPTIONAL).

If present, the data array represents command parameters for the associated href property of the same object. See Command Templates for details.

// samples commands array

{
  "commands": [
    {
      "href": "/users/disable",
      "rel": "disable",
      "name" "Disable",
      "prompt": "Disable user",
      "data": [
        {"name": "id", "value": "", "prompt": "User id to disable"}
      ]
    },
    ...
    {"href": URI, "rel": STRING, "prompt": STRING, "name": STRING}
  ]
}

you mention multipart/form-data here. do you mean application/x-www-form-urlencoded or actual multipart (e.g. supporting uploads)? and how (in this extension) does the client determine which to use when sending a POST body?

@mamund didn't see this comment until now 😦 We use the prompt to inform the developer if this is an upload endpoint or an action and they use the appropriate content-type though we always accept multipart/form-data.