Sales Sessions to DFC API

kirstenalarsen commented 1 year ago

All Global work to be tracked in Clockify #11242 Discovery Endpoints - including testing, code review etc Aus devs to track in #11242 Task within Macdoch Regen Discovery

Description

Following here

On the Discovery site we want to be able to see and link to open Order Cycles on OFN for a particular producer. There are a couple of different possibilities for how we might do this - TBC closer to when we get to it. These include:

Create an Order Cycle / Sales Session (DFC) endpoint that takes producer Id and returns list of open order cycles
~~Use existing OC webhook to update Airtable/database that is feeding the prototype~~
~~Upgrade existing OC open webhook to include Sales Session format fields and make DFC compliant~~
~~Create OC / Sales Session close webhook to maintain the database list for each producer~~

Inception notes

Order Cycle should be supported within DFC Sales Session. There may be a task to adapt webhooks to DFC compliance. Discussion around whether we could add fields so that existing users are not affected, or can we get data on if/how much already being used and potentially just change it

Acceptance Criteria & Tests

*

mkllnk commented 11 months ago

@dacook The order_cycle.opened webhook is our only webhook so far and send information in this format:

{
"id": "job id",
"at": "time now",
"event": "order_cycle.opened",
"data": { "id_etc": "order cycle attributes" }
}

What do you think about replacing this with a DFC document? It would look like this:

    {
      "@id": "salessession/salessessionId1",
      "@type": "dfc-b:SaleSession",
      "dfc-b:beginDate": "",
      "dfc-b:endDate": "",
      "dfc-b:quantity": "",
      "dfc-b:lists": [
          "offer/offerId1",
          "offer/offerId2",
          "offer/offerId3",
          "offer/offerId4"
        ]
    }

I don't think that we need the job id or time but obviously the event name of the webhook is missing. There are several options:

Add a custom attribute like even-context.
Use a webhook endpoint that knows it's this event, e.g. it's encoded in the URL.
The receiver looks at the dates and infers the current state. This may be more accurate anyway because the webhook delivery could be delayed if there was an error. Timing is always tricky.

Within the DFC framework, I'm still not 100% sure how it would work though. We would need to add header options to include an auth key. And the endpoint for opening an order cycle may be the create sale session endpoint. When closing an order cycle, we would use an update sale session endpoint. But that would require the knowledge of the id/url of the sale session.

I'm rambling now a bit but in DFC, each resource has only one id and one source of truth. So if an OFN order cycle is represented as sale session then the source of truth exists only within OFN and it wouldn't be stored anywhere else (except in caches). So there is no other endpoint to send an update to. Webhooks is not part of the DFC standard. So using the DFC format for webhooks would just be for ease of use within a DFC eco system. And it can be used for DFC-aligned implementations that are not quite following the intended use. :exploding_head:

dacook commented 11 months ago

😕 Sounds like you're exploring potential solutions, but there might not be a hard requirement to use a DFC-like format here. Do we need to define a clearer use-case? It sounds like maybe we might need to add a persisted model in OFN for this integration?

For the sake of the conversation though, I'd suggest if we wanted to start using more DFC-like formats without adding unnecessary restrictions, we could simply embed it in the data section (and specify the format) like so:

{
"id": "job id",
"at": "time now",
"event": "order_cycle.opened",
"data_format": "dfc-v1.7",
"data": 
    {
      "@id": "salessession/salessessionId1",
      "@type": "dfc-b:SaleSession",
      "dfc-b:beginDate": "",
      "dfc-b:endDate": "",
      "dfc-b:quantity": "",
      "dfc-b:lists": [
          "offer/offerId1",
          "offer/offerId2",
          "offer/offerId3",
          "offer/offerId4"
        ]
    }
}

mkllnk commented 11 months ago

That would be a tiny step in the right direction but it doesn't achieve any integration with other DFC APIs because you can't use a DFC endpoint as webhook endpoint because the sent data isn't a DFC document. If we pointed the webhook to a DFC endpoint for creating or updating sale sessions then we would have an instant integration to replicate order cycle data on another platform.

Anyway, Kirsten and I think that we won't actually need this for the simplified discovery portal. Instead we will include sale sessions in the DFC API and the portal can just query which order cycles are open at a given time. It's much simpler logic and we can worry about performance and caching later.

mkllnk commented 11 months ago

Updated spec for this issue as first step:

Create SaleSessions#show action to show more information about an order cycle. The route would be /sale_sessions/:id with the OFN OrderCycle id.
List open sale sessions within the enterprise graph which is already shown for Enterprises#show and CatalogItems#index.

kirstenalarsen commented 10 months ago

Est. about a day to do this

openfoodfoundation / openfoodnetwork