There is a suggestion in my shop that JSON:API should be applied to all REST endpoints in our services.
Even fine-grained “action” endpoints, in the interest of consistency. Is this an appropriate use of JSON:API?
Could you give an example? It sounds like someone is say that JSON:API only works for resources which are directly backed by a database record?
Sure, but why can’t that be backed by a resource?
What’s an example of what you’re imagining wouldn’t work?
@bf4 There’s no technical reason why that action above couldn’t be made to appear as a resource, and exposed as a JSON:API endpoint. But the question is: would that be an appropriate use of JSON:API?
Oh, well, we use json:api for everything at my company, including actions. It’s definitely appropriate
I push for using jsonapi everywhere, but it isn’t always possible or practical.
E.g. handling file uploads is not possible with jsonapi. And some more complex actions are just cumbersome. For example multi-faceted search. And I’ve also had action endpoints where a lot of context was needed to handle the call correctly which jsonapi doesn’t support very nicely yet.
It is also not a requirement of the jsonapi specification that all endpoints from a single API are implemented in jsonapi.
But as already discussed creating resources for things that are not an entity / database record is perfectly fine. And if the action you do is close to the core of your product I would try to make it a resource. Or if you notice you’re creating a lot of non-jsonapi endpoints in the core of your product I would rethink your approach. Funds transfer sounds like core, so for example create a TransferFund resource with relationships to a fromAccount and a toAccount.
Using JSON:API for all REST endpoints, including fine-grained “action” endpoints, can be a valid approach to achieve consistency within your services. However, whether it is appropriate or not depends on various factors specific to your use case. Here are a few considerations to help you make an informed decision:
- Complexity: JSON:API introduces a standardized way of structuring responses and handling relationships, which can simplify client-server interactions. However, for simple and straightforward endpoints, implementing JSON:API might add unnecessary complexity. Evaluate the complexity of your endpoints and determine if the additional overhead of JSON:API is justified.
Complexity: JSON:API introduces a standardized way of structuring responses and handling relationships, which can simplify client-server interactions. However, for simple and straightforward endpoints, implementing JSON:API might add unnecessary complexity. Evaluate the complexity of your endpoints and determine if the additional overhead of JSON: API