This post is to summarise some of the discussions on high level API implementation. What follows is essentially a proposal for the wider delivery team, summarising a lot of content discussed in other places alongside some of the discussions we had in person.
1. Documentation
Documentation will be automatically generated by RSwag gem. You can find an example of what this will look like here. Documentation takes info in specs and turns it into human readable Swagger docs. This documentation will be automatically updated when the code is updated, which is obviously excellent. There was some discussion that we might want to add a little additional detail to aid useability, like more descriptive details on attributes. We might also want to add a wiki somewhere that outlines the different ways filtering can be applied.
2. Pagination Strategy
We propose that pagination is implemented on every v1 endpoint. We discussed a few different options and realised that perhaps we just want to start conservative and increase numbers when we have more data about API use. Our proposed starting points are:
- Set the max number of rows returned per request at 200
- Set the default number of rows returned (when no number of rows is specified in the request) to 50. We recognise is low but setting the default to a low number seems sensible.
3. Authentication Strategy
Essentially weâre all in agreement that the authentication strategy remains unchanged between v0 and v1. This means:
- Basic auth via login when API is accessed via browser
- API Key as param
- API Key in header
4. Implementation
The technical framework has been decided through conversations with techie folks in Slack and Github. We propose that new API controllers should be implemented with full CRUD functions from the start. @Matt-Yorkley suggests that there is no point implementing only specific actions on API controllers, that we might as well define and scope all actions upon creation of each API controller.
5. Bug Severity
We discussed how we assign API endpoint severity, and essentially propose that the same fundamental severity ranking will apply as now in v1. If endpoints are suddenly down these will be s2 at least. For performance issues we agree performance is a feature, as always. In designing endpoints the proposal is that we keep calculated fields (eg customer balance) to an absolute minimum and never show field like this on high level index. Endpoints should be nested. Attributes that require heavy calculations might be hidden by default and might exist only on :show. Datadog already monitors endpoints currently, it gives detailed information so we should be able to stay ahead or at least have good visibility on performance. This is important as for the foreseeable future the API will be served over production servers so performance issues could impact all users.
6. V0 Maintenance
The proposal is that v0 endpoints are not maintained going forward. Obviously v0 endpoints that are used by the app will need to be maintained specifically for app use as the app will continue to use v0 endpoints until we have fully migrated to ReactiveRails. To be clear, We wonât transition the app to use v1 endpoints at all. V1 of the API is an entirely separate product to the app. That being said, v1 endpoints might be used in modularisation processes eg /shops page might be turned into an independent and modular app when we work on Discovery, and this app would use v1 (or v2 or vwhatever). The same would be true of modular Shopfronts implemented via the API.
We propose that officially v0 endpoints are now scheduled for deletion and deprecated. This means that by default v0 bugs are not fixed (unless directly needed by the app). Enhancements on v0 not prioritised and rejected by default. V0 documentation wonât be maintained. We understand that a number of instances are using v0 but we propose that if changes are needed any instance using the API should support the development of v1 endpoints if they require changes (via the funded features process). The idea is that once a v1 endpoint is created, we declare an End of Life date for the v0 version (for any endpoint not used by the app we declare an EOL date). In this way the intention is to encourage the community onto v1.
: