Observed Behaviour. There is no way to control which fields are returned as children of the documents field returned by most items in the Open5e dataset.
Desired Behaviour. The ability to control which children of the document field are returned via query parameters. One specific use-case that would be especially useful on the frontend would be to have a way to only return document.name and document.key in the documents property and omit all other children.
Reproduction
1) Visit the Open5e V2 API, I will use https://api.open5e.com/v2/creatures/srd_goblin/?depth=1 as an example but the bug can be observed in many endpoints
2) Click on the Filter button and explore the filtering options for this endpoint
3) Note that there is no way to filter the fields returned by the documents property
Context
It is currently possible to modify fields returned by an API query by including the appropriate query parameter in the endpoint URL. For example, hitting the https://api.open5e.com/v2/creatures/?fields=name,key only creautre names and keys are returned. This is a very helpful feature on the frontend to minimise the size of API responses to keep response times snappy.
However, with how API V2 is currently set up this is not possible on all fields. Specifically, you are not able to filter nested models stored as ForeignKeys. If you hit the https://api.open5e.com/v2/creatures/?fields=name,key,document endpoint, you will see that the document property returns all the data about the document, and that no option exists to request specific nested fields.
At a minimum, being able to request via query parameter that the document field should only return its name and key would allow large improvements to load times on the top-level pages of the frontend website.
Resources
Thanks to Tyler for flagging this article on the Open5e Discord. Within is described a programming-pattern which could provide the functionality requested
Description
Observed Behaviour. There is no way to control which fields are returned as children of the
documentsfield returned by most items in the Open5e dataset.Desired Behaviour. The ability to control which children of the
documentfield are returned via query parameters. One specific use-case that would be especially useful on the frontend would be to have a way to only returndocument.nameanddocument.keyin thedocumentsproperty and omit all other children.Reproduction
1) Visit the Open5e V2 API, I will use https://api.open5e.com/v2/creatures/srd_goblin/?depth=1 as an example but the bug can be observed in many endpoints 2) Click on the
Filterbutton and explore the filtering options for this endpoint 3) Note that there is no way to filter the fields returned by thedocumentspropertyContext
It is currently possible to modify fields returned by an API query by including the appropriate query parameter in the endpoint URL. For example, hitting the https://api.open5e.com/v2/creatures/?fields=name,key only creautre names and keys are returned. This is a very helpful feature on the frontend to minimise the size of API responses to keep response times snappy.
However, with how API V2 is currently set up this is not possible on all fields. Specifically, you are not able to filter nested models stored as ForeignKeys. If you hit the https://api.open5e.com/v2/creatures/?fields=name,key,document endpoint, you will see that the
documentproperty returns all the data about the document, and that no option exists to request specific nested fields.At a minimum, being able to request via query parameter that the
documentfield should only return itsnameandkeywould allow large improvements to load times on the top-level pages of the frontend website.Resources
Thanks to Tyler for flagging this article on the Open5e Discord. Within is described a programming-pattern which could provide the functionality requested