Document our API


#1

What is the need / problem:

In 2 words: enable users to start integrate OFN with their custom tools, they can start using it if they want

The OFN has today a pretty wide, messy, ununderstood and undocumented API.
Meanwhile, more and more users ask us if we can provide them with our API so that they can : build customer reports, integrate with a warehouse management tool, integrate with accounting packages, integrate with POS, etc.

Who does it impact and what is the impact

Some hubs in all instances, and especially potential big actors like wholeselers that can’t use our system. Those users are the ones who potentially have more volumes sold, and are quite big contributors in our business model. So instance managers are also impacted in their capacity to build a sustainable business model.

What is the benefit in focusing on this

Time efficiency for food enterprise managers, who are the ones we want to focus on serving.
Ability to attract and gain high-volumes hubs who can be significant contributors in local business models.

Potential solutions that will solve this problem

1- To meet that very first level of need (get access to our API) there is one obvious feature candidate: document our current API so that the link to that documentation can be shared upon request.

Value x ease analysis and selection of our feature candidate

NA (only one candidate)

T-shirt size of the selected feature candidate

@luisramos0 said he would need 5 days, like 30 hours.
And @Matt-Yorkley @sauloperez @luisramos0 and @Hugs agreed to size it “L”

Metrics to measure if need is well satisfied after feature has been implemented

  • Any OFN team member are able to access and share information on existing API (= they all know where it is)

Epic and/or project board where you can follow implementation

To be open when it is prioritized.

First brainstorm on story map

Apparently given the devs mentioned above it will be only one story.


Connected wishlist and product / tech discovery discussions:

Tech discussions:

Product discussions:
General customer requests summary: Enabling OFN to integrate with external systems (POS, standalone websites, Odoo ERP modules, other plateforms with DFC sandard, etc.)


WIKI - ordered delivery backlog (pipe-ready and in delivery)
#2

Adding some inputs on why I think the product curation team should prioritize that ASAP. In UK people are asking for customer dashboard for instance. UK team has been able to setup some zapier to find some way to answer those needs.

In France there are various users who asked us our API. They didn’t even ask us to integrate or do anything, just the info on “do you have an API” because they know devs who can build things on it (custom report and integration with warehouse management tool). The fact that we cannot even just share a link of “hey, here is our API, it’s not tested and we don’t know if it does the job, but here it is you can play with it” would at least be a first level of answer. Also those users by starting to build things on it can contribute to help us improve it. If we have no answer to give, at least even a timeframe on when we’ll be able to share a link on “what is”, I’m afraid we might loose important users. Who are those we count one for our business model as well.

More generally lots of integrations are required by various instances, whether it be for marketing tools, accounting, invoicing, POS, warehouse management tools, dashboard, etc. Even before thinking of integrating OFN with whatever tool, we need to understand what is in current API and document it. It is more like “spike”, but not a trivial one, would take a bit of time. @oeoeaio had started to do some investigation, @luisramos0 as well, there has been so much time spent in discussing that doing that spike earlier might have saved us time (and money) and discussion will keep on going, integration has been a core topic since long.

@Kirsten @danielle it is not a feature in itself, I would say it’s for the curation team to prioritize within the pipe. So I put it directly in pipe-ready, and we can discuss on where we should prioritize in between the various features that are in queue. If you think it should go through wishlist and be voted by the whole community first we can move it back to wishlist and let it collect votes first.


#3

I would actually call this tech debt Myriam, and therefore not even worthy of putting in here as a feature?


#4

@luisramos0 @sauloperez @Matt-Yorkley @maikel @kristinalim @Hugs if you agree with Danni, then it’s up to you to move it forward in the tech debt backlog and prioritize in the tech debt context. Do you agree?


#5

I strongly disagree. API is a feature, a very important feature of the system.
There are many many references where you can read about this.

The implication is: if you and the community don’t think this API work is a top business priority then, we shouldn’t do this task.
For example, with upgrading dependencies (obvious tech debt), if you and the community dont think it’s a top business priority, we should do it anyway because code needs to be maintained and kept, at least minimally, up-to-date .


#6

The API is definitely a feature @luisramos0. The documenting of the existing API without changing anything is in my eyes an oversight in the work that should have been included as that API was developed. See the difference?


#7

Yes, it’s the same.
I think you can call it a bug of an existing feature if you think it “should already be there”. I think we should consider we dont have the feature called API at all and this is the first step (a spike) to get it started.


#8

The OFN has today a pretty wide, messy, ununderstood and undocumented API.

Maybe I’m incorrect in my understanding of the word “has” for this item @luisramos0 @MyriamBoure?

If this is the first step in doing a bigger piece which is the development of APIs beyond what we have now, for all the reasons we’ve talked about, then why don’t we call it that and have the first step as documenting / spiking what we have rather than what’s above? That spike would be part of the discovery process, I would think…?


#9

Is this not relevant/up-to-date anymore: https://github.com/openfoodfoundation/openfoodnetwork/wiki/API-documentation ?


#10

The feature request here is really “The OFN has today a… undocumented API.”
Which means, it doesn’t have a usable API.

@sigmundpetersen that page is 3 years old and contains a fraction of the endpoints. The result of this work would be an up to date page like that one.


#11

I agree about the “spike”, I mentionned that term earlier, we are in a discovery stage about having a usable API, how do we have a usable API? We need first a spike in this discovery process. But I think the community should prioritize the wishlist: “OFN has a documented API so users can start to use it” to legitimate that we spend time on this and not on building network first, you see? So I would propose to move that back to wishlist to get the community agreement on how prioritary having a usable API (= documented API, not changing anything). Agree?