What is the need / problem ?
OFN has an API. It is used by the app, by Zapier, and increasingly by people wanting to use OFN and solve problems we’ve not solved. Increasing we are seeing the need for a clearly specified, well defined API.
For a long time the API has not been treated as a first class citizen. Much of the API was originally part of Spree. Although the API was brought into the OFN code base about a year ago the json responses still are based on the Spree implementation. In many cases this results in ugly json that requires a lot of post-processing to create something meaningful. This is particularly true for anything that touches adjustments!
We all agree that the API should be a fully supported feature of OFN - a first class citizen. There is reasonable agreement that this should happen as fast as possible. This post aims to make some first proposals of a roadmap for what needs to happen to make the API a first class citizen.
What does it mean for the API to be a first class citizen?
For the API to be a fully supported feature I propose the following acceptance criteria:
Official OFN API docs - the current docs are listed under a personal swagger account belonging to Luis and marked at v0.1. We need an official OFN account to own the documentation. This is apparently very easy to switch.
Clarity over which endpoints we are officially supporting now. Once endpoints are officially supported we will have a responsibility to users upon changing them. We will have a responsibility to fix bugs. Although we don’t officially have SLAs and Ts&Cs (another story) if the API is to be an official feature we will prioritise rollouts and bug fixes as part of our processes.
We will have clarity as a team over how the API fits into our processes. At the very least we will share an understanding of constitutes a bug of different severity. No doubt many of our processes will develop over the coming months, and the API will be included.
Some bigger picture questions
A bad API will likely create more work for us than no API. Certainly more than a clean, clear, well designed API. API design is a skill. Do we want to invest in API design or do we have the skills in the existing team?
Some endpoints are really messy. How much time are we putting into the API now? What is in scope and out of scope for v1.0?
How do we handle endpoints we need (and are used) but would benefit from refactor before being officially supported? For example do we want to release the /orders endpoint in v1.0 as is? Or will we exclude from v1.0, refactor it and release it later? Or will we work on it before v1.0?
What are the next steps?
Discussions on which endpoints will be officially supported in OFN API v1.
- Who will participate in these decisions?
- What factors are important to consider? Eg usability, need, work required
- When do we want to know this by?
- How will we prioritise work that needs to be done?
Checking and confirming the existing docs for clarity and accuracy
Agree some processes around the API
- What constitutes a bug of different severity within the API?
- Do we want to agree a process for API releases? For rolling out API changes?
- Do we want to consider acceptance criteria for future API updates?
Publish the documentation in an official OFN account at v1.0.
What is the need?
To be able to CRUD OFN data on OFN data objects (eg enterprises, order cycles, shoppers, orders, products, inventory).
This is the beginning of a list of things that either we are currently using either the API, the Zapier DB link or reports downloads to do, or that people have asked for:
- to maintain orders within an accounting system
- to plan distribution routes
- to create shoppers
- to place orders
- to extract data for packing lists
- to extract shopper data for CRM tools and newsletters
- to update and edit orders
- to find enterprise addresses
- to find order cycle details
A Roadmap for the API