Introduction
This post is a brief description about Practical PHP APIs with Symfony that I have recently published in Leanpub
When deve...
For further actions, you may consider blocking this person and/or reporting abuse
After reading the post and the comments I don't see the real benefit.
It looks you are pointing out that it is required to have a one fragment url in the post. But in the comments you acknowledge multi fragments are ok. It is true /send-payments or a variation is ambiguous. But an url like /account/{id}/send-payment gives all the context and you only need to and amount as payload.
You say there is no limit to operations. But where is the limit in making urls? Both things do the same, creating a hook to do things
I see the benefit that the payload gets fast in the system. But why would you want to add all the throttling, permissions, and so on to one controller instead of multiple. This could be a mess very soon if it doesn't get handled correctly.
A thing developers don't like to do is write documentation, and with that one endpoint you need to write all the cases. If you have multiple endpoints, you are already writing documentation with the code.
While it feels like a great way of working. My opinion is that the benefits are too shallow to make a valid way of working.
Hey David, thanks for your comments.
This approach can be beneficial if we combine it with the traditional approach. For instance, we could have a controller with the following routes:
And then, form more complex operations we could use an operation-oriented approach,
With the last endpoint, we could handle operations such as send-payment, approve-order, sync-to-x etc. This operations could be organized within a collection using Symfony features. I think this can help to reduce the number of endpoints within the controllers and have them better organized . Crud operations would be handled as always and non crud operations would be handled with an operation-oriented approach.
With respect to "You say there is no limit to operations. But where is the limit in making urls? Both things do the same, creating a hook to do things": Yes, you are right, there is no limit in making urls. I think it's a matter of preference., I like organizing complex operations as services instead of having many endpoints.
With respect to: "But why would you want to add all the throttling, permissions, and so on to one controller instead of multiple. This could be a mess very soon if it doesn't get handled correctly.": No, i don't agree:
With respect to: "A thing developers don't like to do is write documentation, and with that one endpoint you need to write all the cases. If you have multiple endpoints, you are already writing documentation with the code." : Yes, I can't argue with that. This approach would require documenting each operation separately.
Again, many thanks for your comments. For me its fantastic having developers feedback :)
Thank you for the article. But why not
ApproveOrder — POST /orders/id/approve
SendPayment — POST /payments (send payment = create payment)
SyncData — needs more context to give an alternative example :)
Hey, Thank you for your comments:
POST /orders/id/approve: It's completly valid. It's simply that this article approach consider the "operation" as the main resource so that we can send "performing requests" to the operation endpoints. This gives flexibility for creating operation names and reduce the number of endpoints.
POST /payments: Can be ambiguous since does not specify exactly whether the call creates a new element on the payment resource or it sends the payment.
SyncData: Similar to approve. Let's imagine we have two systems A and B and we have to sync user data from A to B. We could:
Both approaches are valid, but, the operation-oriented way allows us to be more descriptive in a cleaner way:
The second endpoint can play with the operation names leaving the url simple and readable.
I would like to emphasize that I have not written this book to present an operation-oriented approach as an alternative to other approaches, but as another option that can be applied by developers if it suits the needs of their project.
Thanks again for your comments :)
Very nice approach. I prefer buses with commands and command handlers instead, but this is a very clean and maintainable way.
Thanks for your comments!
"buses with commands and command handlers instead" -- You mean CQRS, don't you ?
Yes, of course. The thing is that you encapsulate all operations/use-cases/actions into a dedicated class which its unique purpose is to perform the related functionality. Even when you don't have CQRS this way is very good. I worked on projects without buses but commands and handlers.
Great! I will investigate more about CQRS so i would like to write a post comparing my approach wit CQRS.
Thanks again!
Perfect
Great article, would like to see a similar approach on Laravel.
Hey, thank you. I am not a regular Laravel user but i will study it and try to write an article for a Laravel aproach. Thanks again!