farmOS 2.x Support

[paul121]

More info on the farmOS 2.x roadmap: https://www.drupal.org/project/farm/issues/3092830

Perhaps most notable for the Aggregator are changes to the farmOS server API: http://2x.farmos.org/api/changes/

These API changes will also be reflected in the farmOS.py API: farmOS/farmOS.py#39

Since the Aggregator exposes endpoints that are largely coupled to the farmOS.py API, we need to decide how to support both versions concurrently:

As @mstenta noted in #97:

We'll still need to support the endpoint for 1.x sites - there will be a period of overlap when some sites are on 1.x and others are on 2.x.

There may also be cases where a site gets upgraded to 2.x, but there are still requests being made to it using the old endpoint.

Maybe we add support for 2.x alongside 1.x, with deprecation notices, and then eventually make the decision to drop 1.x support (perhaps by bumping the Aggregator itself to 2.x, similar to what we'll be doing in Field Kit). Then, anyone hosting the Aggregator can decide when to jump to 2.x, based on the sites that they need to connect to, and whether or not they've all be upgraded.

---

TODO:

• Update farmOS.py dependency Update farmOS.py dependency for 2x support #99
• Use farmOS.py iterator to GET all resources Use iterator to GET all resources #100
• Deprecate areas: Deprecate areas #97
• Endpoint to get ALL entities (log, asset, term) is deprecated (a bundle is required) Endpoint to get ALL entities is deprecated #101
  • If no bundle is provided, should we automatically request each bundle? (creates other issues)
  • OR Require a bundle in the API endpoints
• Add generic "resource" endpoint Add generic "resource" endpoint #102
• Update/re-visit storage of farm.info (new JSONAPI structure) Re-visit storage of farm.info #103
• Support changes to OAuth scopes Support changes to 2x OAuth scopes #105
• Re-authorize farms Re-authorize farms #104
  • Provide a helper script?
  • Consider migrating access tokens in farmOS server?
• Test refresh token bug with 2x servers Failures refreshing OAuth tokens #91

[paul121]

TLDR; after documenting these todos, I really think we need to enforce that the Aggregator API version matches the farmOS server version (/api/v1 can only be used for servers running 1.x, and /api/v2 for 2.x). If the wrong API version is used, the Aggregator can return a HTTP Method not allowed error or similar. Additionally, before making a request, the client could request the farm.info to determine its version (notably this doesn't require a request to the farmOS server, the Aggregator maintains this info in its DB), before making a request to the appropriate endpoint.

FastAPI will allow us to maintain both v1 and v2 API endpoints. It also has methods so that we can re-use logic wherever possible. Down the road, removing v1 would be easy (or even configurable in the Aggregator env settings!).

@mstenta I know we also mentioned a translation layer provided by the Aggregator, but this seems like it just pushes the problem for later. The best way to utilize the new API format.... is to just use it. Perhaps most important are the different response and POST formats between 1x and 2x (something I didn't mention above!).

Consider the following: if a single request to an aggregator endpoint (eg: /api/v1/log) will return different response formats for each server, depending on which version the farmOS server is running (the same goes for POSTing data). When the server version and API path are not enforced, this is added complexity the client using the aggregator MUST be able to handle. The client must have logic to check the individual resource responses returned (eg: a logs data) to determine the structure and handle accordingly OR keep internal state of which version the farmOS server is running, and handle accordingly.

Enforcing the server version on the API makes the client logic much simpler: rather than checking the structure of returned data, the client will know what to expect when making a request to either /api/v1 or /api/v2.

This also simplifies #97, #101 and #102 since each version of the Aggregator API can have different (more or less) endpoints, and each endpoint can behave differently than its /api/v1 counterpart (requiring a bundle param, etc).