Json-api: Add custom actions to resources

[fpahl]

We would like to add custom actions to our API. For example:

• A user login request, like /users/login
• Other actions like sending a message, /users/1/sendmessage?subject=helloworld

Does the specification handle these types of request?
How might the requests and responses be composed?

[tkawa]

I have the same question.
How can I express this form as JSON API?

<form action="/shopping_cart/buy" method="post">
  <input type="submit">
</form>

[hhware]

@johnpaul2, @tkawa, the position of the current version of the spec on this is wide open, see the following questions in the FAQ:

• How to discover resource possible actions?
• Does JSON API take any position on URI structure, on rules for custom endpoints, which do not fit the paradigm of GET/POST/PATCH/DELETE on the resource URI, etc.?

There are plans to address this topic in one of the future releases of JSON API, see https://github.com/json-api/json-api/issues/684 and issues referred to therein. To bring this future nearer, you are welcome to participate in these discussions.

[tkawa]

Thank you @hhware.

You should use the OPTIONS HTTP method to discover what can be done with a particular resource. The semantics of the methods returned by OPTIONS is defined by the JSON API standard.

A server can respond with Allow: GET, HEAD, POST header not only for OPTIONS but also any request. It makes sense.
Still, I'd like to express parameters required for 'custom actions'.
I'm going to read #684 with great interest.

[ethanresnick]

Still, I'd like to express parameters required for 'custom actions'.

@tkawa What you're talking about is write templates, I think. See https://github.com/json-api/json-api/issues/619. Those won't be part of the spec for a while, though. In the mean time, the best way to get this functionality is to reformulate your request as a standard POST to a JSON API collection, so that your client can rely on the conventions JSON API gives to know how to structure its request. That is, I'd make POST /shopping_cart/buy into POST /shopping_cart/relationships/items, where items is a relationship that the client can then use the standard POST format that JSON API defines for adding to a relationship.

Likewise, @johnpaul2, you could do a similar thing with your proposed actions. I talked about that a bit here, about half-way down the comment.

[ethanresnick]

Gonna give this a close, since I think everything here is being worked on in #684 and #745

[beauby]

For future reference, @johnpaul2, you could view logging in as creating a new session, thus you could do a POST to /session and you could view "sending a message" as "creating a message", thus you could do a POST to /messages with params like the receiver in the payload.
@tkawa you could view your shopping_cart/buy action as creating a payment, so POST /payment.

[greyblake]

It doesn't work for all situations.. Sometimes we really need custom actions. Otherwise we need to create a number of resources with fancy names.

Is there a chance to reopen this issue?