Create an additional .getId() method to support getting resources by ID

[paul121]

Why

We currently support passing an ID to the .get(type, filter) method's filter parameter to request a single resource. #14 would allow a list of IDs to be supplied here.

For the farmOS 2.x API, filters should really be renamed to params. This is because JSON:API supports many additional features via query params: Filtering, includes, pagination, sorting, revisions and translations. Notably, some of these features apply when fetching even a single resources. For this reason I don't think we should accept an ID instead of a Dictionary (or object) of filter params; there are times when both parameters need to be supplied.

Another reason to move the ID to a separate method is because the response of a single resource is different than the response of multiple resources. Fetching a single resource, such as /api/log/observation/f1790e98-8762-4c16-bb93-ef53f0f77dfe returns a single object in the response data property. Fetching a collection of resources returns an array in the data property. This is change from the 1.x API where IDs were simply added as "filters". Previously when fetching a single ID via the client, the response would contain a list property of length 1.

The core JSON:API schema specifies that data can return a single resource, an array of resources, or null. Since POST, PATCH and GET to a single ID will always return a single resource in the data property we should provide proper return types for the API client methods that perform these behaviors.

Proposed resolution

• Rename the filters parameter in all methods to params (or maybe options?)

• Add an additional .getId(type, id, params) method for requesting a single resource by ID.

• Re: Accept an array of id's as a .get() parameter #14, requesting multiple resources by ID can be done by providing the corresponding filter to the resource.get(type, filters) method. Example:

filter = client.filter('id', [id1, id2, id3], 'IN')
# the raw parameter would look like ?filter[id-filter][group][path]=id&filter[id-filter][group][operator]=IN&filter[id-filter][group][value]=[id1,id2,id3]
logs = client.logs.get('observation', filter)

[paul121]

Added this in v1.0.0-alpha.2: https://github.com/farmOS/farmOS.py/releases/tag/v1.0.0-alpha.2