@Rachel asked this question here
“After the API clean up epic is done, would our API already be usable for external integration or is there more work to be done before that?”
That’s a good follow up question from the API clean up Rachel. I think that’s a team decision, that’s why I open this thread.
Some of our existing payloads are a bit of a mess, see products and orders for example, all sorts of fields in there, if we make external clients depend on these fields we will need to maintain them for a long time… (welcome to the world of API: this is the basic public API problem, it’s a good problem to have, it means we have an API 
)
Products and orders payload examples:
I think we should be careful about what fields we let external clients depend on…
In a larger scale scenario this would mean we should have an internal API and a public API, I dont think we should do that now in OFN: too much work.
So, my answer to your question is: if everyone agrees, YES, it’s ready to be used. Let’s just be careful with what fields the external clients will use.
Because this is not going to be large scale (yet!) I think we should keep track of all our API clients and what endpoints and fields they rely on. What do you think about this suggestion?
I’d love to follow the suggestion and limit the fields that external clients can use.
Can we say we only support certain fields? So we don’t code change but we document the fields that have been deprecated while we improve the API?
Just a thought…
yeah, something like that. Either use deprecation or a list of the fields actually available for use.
Cool. It’s great to be finally in the position to talk about this. It will be very difficult to restrict usage without enforcing it on the server side. Users may also wonder why we restrict something and why they can’t use what’s there. Of course, our intention is to be flexible and be able to change everything. But we have no idea yet what will be changed and what we will keep. And that will depend on the usage as well.
I would say that our API is available, yes, but without any Service Level Agreement. It’s declared as alpha, version 0.1 and can change at any time. We ask all users to tell us which parts of the API they are using and which information they are interested in. In return, they can get notified when we change stuff so that they can react to it. And we can take that data into consideration when developing. That document can be the base for future API development.
Once we have a few stable users and we know that the API makes sense in that way, we can declare that part of the API as stable.
I was thinking of a separation of internal and external API but I don’t think that it would help us. We should use our own API. It could just be that we have a stable API and a development API and our app is always using the development API. That keeps us flexible while maintaining consistency for the public.
1 Like
awesome Maikel, I totally agree.
We will have to consider having a private and public API at some point in the future. I see the benefits of having a split API but I think having a single API for public and private can have major benefits for our architecture because if we use our API to build our app it means other external teams can also build apps on top of our API. Also, I think v0.1 can go a very long way.
On another note, I am going to create a couple of issues to further clean up the API (to make it more consistent with the exemplar). If users want to use specific endpoints in the existing API they should let us know first so that we can clean up before they get into it.
Examples are:
- move /api/products/{product_id}/soft_delete to DELETE /api/products/{product_id}
- move /api/products/{product_id}/variants/{variants_id}/soft_delete to DELETE /api/products/{product_id}/variants/{variants_id}
- remove .json from a few endpoints like in /api/orders/{order_number}/shipments.json
- remove verbs from urls like moving POST /enterprises/{enterprise_id}/update_image to PUT /enterprises/{enterprise_id}/image
- etc
1 Like
Agree with everyone. I would clearly state that it’s alpha and can change anytime. In any case, I don’t expect we’ll suddenly have tons of API clients though.
Don’t underestimate our potential of API clients 
This means we really need to be careful about our communication.
I understand what it means to have an API in alpha mode, but I’m unsure all instance managers / users are fully aware of the consequences.
So explaining there is no SLA and things can break often can sometimes take a lot more time than saying to some targeted audience that our API is not ready yet…(but we’ve just reached an important milestone)
One alternative would be to publish just the endpoints we think are good (and stable) to be used like listing products, orders, etc. To be clear, our API is 100% ready to be used for some of the endpoints. These two endpoints “list of products and list of orders” have alone a great potential, isn’t it?
But I think the best approach is to declare it public and in alpha mode and build a roadmap based on user needs from there. I think building a API roadmap is the most important thing now: what exactly users need from our API?
1 Like