Implement the shiny, new REST API v1
CrsiX opened this issue · comments
Crsi commented
This issue is used to keep track of all the different tasks needed to be solved for a working and stable API. Some of those tasks may be delayed back or completely dropped -- it's also a raw collection of ideas. If any of those tasks seems to grow in size too heavily, it could be split out into its own issue as well.
General
- Mark the API as version v1 as soon as it's finished
- Add a configuration for the MateBot core API project
- Add a
config
schema module which can be used to validate the JSON config (#75) - Add offline CSS/JS bundles for the docs UI
- Add an icon for the MateBot
- Add an favicon for the MateBot which is used in the swagger / redoc API overview pages (e.g.
/docs
) - Get a list of all locations where versions are somehow mentioned to create consistency among them
Assertions
- Ensure that redirects and failures take precedence over the evaluation of preconditions in conditional requests (see RFC 7233)
- After successful DELETE requests, return code 204 (and no ETag header!)
- Every critical database
commit()
action should be in a try-except block since error handling would not be possible otherwise! - Make sure that the
details
field of theAPIError
schema always contains JSON-parsable content (not only string, but also some better information, e.g. always some kind of JSON-formatted object, but no lists!) - Ensure that the CHECK constraint for vote values works on the target database, too! Add a unit test for that.
- What happens when a user should be deleted? Cascade (delete) all the transactions, votes, polls, ..., where it was involved? That shouldn't be the case. Should the community user take over all old transactions? => No, users can't get deleted, they will just be permanently disabled.
Features
- Add consumables to the updates schema
- Add support for consumables, using a simple 'GET /consumables' or something, which contains all necessary data
- #98
- Add a simple way to consume goods (i.e. make transactions for consumables as easy as possible)
- Implement the
healthy
metric for 'GET /status' - API callbacks are a fancy way to avoid polling: https://fastapi.tiangolo.com/advanced/openapi-callbacks/
- Re-work the /communisms endpoint (currently ugly)
- Re-work the /refunds endpoint (currently ugly)
- Add active flag, "closed" timestamp and result to ballot model & schema!
- Make use of the User.active field
- Add support for access logs in extra log files via uvicorn configuration (
uvicorn.config.LOGGING_CONFIG
) - Add fancy new callback API option instead of polling for clients that provide a HTTP server as well
- Add some kind of per-application key-value storage which can be accessed via API easily (this should ideally make any client-side data storage superfluous)
- Fix/improve/remove weird logging of sqlalchemy
- Fix problems with 'GET /users' since deprecated data in DB creates ValidationErrors
- Management of external users
- Add handling of the "special user" in various applications
- Add an "easy" way to tell if some API endpoint changed during different versions (automatically, without looking into changelog files)
- Re-build the helper functionality to be cleaner
- Look through all "old" code to cleanup deprecated functionality
- Make use of improved helper and hook functions
- Add valid & correct application shutdown
- Close the session of the class
Callback
inhelpers
module - Add a "shutdown" message to logging
- Close the session of the class
- Rename 'Ballot' to 'Poll' in all cases
Feature requests
- Add a new
config
endpoint - Add
errno
or some kind of unique, unambiguous declaration of the error to theAPIError
scheme - Add
error: False
to all return schemas, except for theAPIError
schema, where this is actuallyTrue
- Add additional currencies with conversions to the internal "amount"
- Add option how to calculate ETag header values (see commit 9fa5ebb for difference!)
- Add some kind of "power" level to the user model and as requirement to some actions, e.g. vouching for someone else or taking part in a ballot etc. -- this could be used to overwork "external" users, too
- Add a versioned schema definition (using a sub-package for version v1 of the API) -- so that a v2 may use any of the "old" schemas, but may also replace, delete or add some
- Allow users to join more than once to a given communism (maybe even adding a completely new feature for this?)
- Add a read-only endpoint (including the required database tables) for multi-transactions (like communisms, but more general)
Debugging
- Debug problems with my new shiny error handler APIException.handle and RequestValidationError
- Fix logging problems of uvicorn and allow to see the colorized logs in the console again
- Fix Validation Errors upon GET transactions, ballots and votes
- Fix problems of ValidationErrors in
APIError
schema when an unknown HTTP method (not something like e.g.GET
orPOST
has been used) - Known limitation of ETag handling: if multiple If-Match / If-None-Match headers are set, only the first will be used
Docs, QA & unit tests
- Add other databases to the CI pipeline checks as well (not only
sqlite3
backend) - Create a collection (for docs) of GET endpoints to call to update the WHOLE local cache/state
- Add some more fractions to test
- Deleting a user
- Deleting a vote (which may work, depending on the
restricted
flag) - Deleting a ballot (which shouldn't work)
- Fix race conditions in unittests (e.g.
test_users
, where a cached version of the user model is PUT to the server but may be rejected for being just one second too old)
Endpoints
- Implement
/aliases
completely - Implement
/applications
completely - Implement
/ballots
completely - Implement
/callbacks
completely - Implement
/communisms
completely - Implement
/consumables
completely - Implement
/refunds
completely - Implement
/transactions
completely - Implement
/users
completely - Implement
/votes
completely - Implement
/settings
completely - Implement
/status
completely - Implement
/updates
completely
Callbacks
- Add the callback router definition
- Add triggering the callback mechanics upon certain steps in the API, namely CREATE, UPDATE or DELETE
- Add unittests for the callbacks as well
Packaging
- Create a
setup.py
file - Add the package creation to the CI pipeline
- Make an extra section in the requirements.txt file or somewhere else to allow optional 'ujson' dependency with "pip install matebot_core[extras]" later