inventree
[API] Reduce hidden mutations
Body of the issue
A lot of API endpoints can be "mutated" by passing extra parameters (e.g. ?part_detail=true). These parameters are largely undocumented and should be re-implemented as API filters. This will expose them to the API schema documentation.
I’d like to take on this issue. Is there any additional context or details I should know before starting?
@Reza98Sh With the limited work you have submitted to the backend I am not sure if you have found all the trip-hazards that are hidden in the way our backend api works, but you have shown potential in other work so sure, go ahead. Just let us know if you need pointers.
Just to re-iterate the problem and what would be considered a "solve": Problem: We currently have parameters in the serializers that adapt the form of the API response. https://github.com/inventree/InvenTree/blob/0bed5cf5112f57cc7d53e622c4596ac6eb8d0696/src/backend/InvenTree/build/api.py#L377 If you look into the OpenAPI schema you will see that this parameter is not represented there https://github.com/inventree/schema/blob/38ab7363cf0b1fcedc3e4994fbf5b351db2473bd/export/385/api.yaml#L1964-L2152
There are at least 2 anti-patterns, that should be addressed:
- parameters that completely change the output schema - probably a lot of work, diving deep into drf serialisation and OpenAPI schema generation
- parameters that add filters that are not documented - easier as one can use proper django-filter filtersets / fields and that automatically gets picked up by schema generation
Goal: A "solve" would be to eliminate 2 completely and proposes a working solution for addressing 1
The whole issue was discovered by @1337joe as he is generating a client library from the schema and these mismatches lead to missing arguments/broken requests.
I think this issue is probably best addressed by a number of small PRs that tackle a few API endpoints at a time, as a large PR that does everything might be time-costly to review and correct.
I have changed the milestone, I think it is realistic to tackle this with the next feature release