Suggested protocol changes
27 views
Skip to first unread message
Andrus Adamchik
May 26, 2022, 5:46:53 AM5/26/22
to Agrest Framework User Group
Hi there!
So the first milestone of Agrest 5.0 approaching. The initial reorganization scope [1] is finished (*) and the new documentation is being written [2]. With so many changes, figured we'd add one more - cleaning up the protocol:
1. In the "simple" response object, remove "success" property. This property gives the client the wrong idea. For response status we must encourage the client to check the HTTP status code, not the JSON payload.
2. In the "sort" JSON object, rename "property" to "path" for symmetry with "include" object. They are both the same thing.
3. On the "sort" JSON object, rename "direction" to "dir" to match the "dir" control parameter name. They are both the same thing.
4. Sorting "dir" value should to be case-insensitive. Upper-case ASC, DESC really stand out in the URLs.
The good news are that the items 2,3,4 can be implemented in a backwards-compatible way. So one #1 is kinda of a breaking change. But I really hope that #1 is not a practical upgrade concern, and client implementations are already doing the right thing, i.e. checking the HTTP status code.
Comments?
Andrus
[1] https://groups.google.com/g/agrest-user/c/Cw2yE4LMvu0
[2] https://agrest.io/docs/5.x/
* Except getting rid of DI core. DI is very useful, so decided to keep it at least for now
So the first milestone of Agrest 5.0 approaching. The initial reorganization scope [1] is finished (*) and the new documentation is being written [2]. With so many changes, figured we'd add one more - cleaning up the protocol:
1. In the "simple" response object, remove "success" property. This property gives the client the wrong idea. For response status we must encourage the client to check the HTTP status code, not the JSON payload.
2. In the "sort" JSON object, rename "property" to "path" for symmetry with "include" object. They are both the same thing.
3. On the "sort" JSON object, rename "direction" to "dir" to match the "dir" control parameter name. They are both the same thing.
4. Sorting "dir" value should to be case-insensitive. Upper-case ASC, DESC really stand out in the URLs.
The good news are that the items 2,3,4 can be implemented in a backwards-compatible way. So one #1 is kinda of a breaking change. But I really hope that #1 is not a practical upgrade concern, and client implementations are already doing the right thing, i.e. checking the HTTP status code.
Comments?
Andrus
[1] https://groups.google.com/g/agrest-user/c/Cw2yE4LMvu0
[2] https://agrest.io/docs/5.x/
* Except getting rid of DI core. DI is very useful, so decided to keep it at least for now
Andrus Adamchik
May 28, 2022, 5:06:50 AM5/28/22
to Agrest Framework User Group
The changes are on "master" and in the 5.x docs. See the GitHub task for the final protocol conventions. There were some private suggestions that were incorporated after my initial post (the main one being to use "direction" instead of "dir").
Andrus
Andrus
Reply all
Reply to author
Forward
0 new messages