Media Type for Action Responses

[dominicbarnes]

In my siren client, I've been setting Accept: application/vnd.siren+json for all requests. Since I was generally just navigating an API from entity to entity, this was a very straightforward thing to do in early versions. However, links and embedded entities can specify the media type for the resource that will be found at the given URL. Because of this, I'm changing my client logic to set the Accept header more intelligently in these cases.

I'm finding actions to be different in regards to content-negotiation. They can specify a media type for the request body, but not for the response body. The spec doesn't make any mention of what media type an action should be met with, and it seems like another siren entity is a pretty common use-case. (though I'm sure not the only use-case) In lieu of nothing being specified, I will probably use Accept: application/vnd.siren+json for my API actions, but I wonder if this is something the siren spec should at least mention?

As for my ultimate question/proposal: should actions be able to specify a media type for the response body? (this would be an addition to the spec, of course) Or should a siren-based client submit actions with the expectation that the response will be another siren entity?

[mcintyre321]

I think your client should just send a list of the media types it can (or wants to) accept, a la vanilla HTTP That should probably include vnd.siren+json.

[dominicbarnes]

@mcintyre321 yeah, that's what I'll be doing. But the server should be able to make this indication to the client just like it does for links, at least in my opinion.

[MathiasReichardt]

I would like to add that this seems a bit RPC like to me. How about creating a Action resource on POST. The response (201 created) would contain a location header wich leads to the created resource.

The Action resource (Siren) may contain things like:

• state (pending, executing, completed, error..)
• result resouces
• error description
• requesting user
• ...

Might be a bit much 😄

[dominicbarnes]

@MathiasReichardt so, are you saying that a Siren action can only respond with application/vnd.siren+json, and the entity returned may contain links to other resources that may be other media types? (seems kinda inflexible to me)

I stand by my assertion that by allowing links to specify the media type for their response body, it also stands to reason that actions should be able to do this too.

[NoMemoryError]

I stumbled upon a similar use case where one of my siren actions is expecting a response type to be application/vnd.openxmlformats-officedocument.spreadsheetml.sheet but unfortunately, the spec doesn't cover this apparently. It would be nice if we can have this addition.