Open josecelano opened 1 year ago
@da2ce7 @WarmBeer
I've found this interesting issue https://github.com/tokio-rs/axum/issues/50 where people are asking Axum to add support for generating OpenAPI/Swagger docs.
And some mentioned that you could use utopia. It has support for all the major web frameworks.
The rqbit - bittorrent client in Rust uses this very useful API entrypoint:
{
"apis": {
"GET /": "list all available APIs",
"GET /dht/stats": "DHT stats",
"GET /dht/table": "DHT routing table",
"GET /torrents": "List torrents (default torrent is 0)",
"GET /torrents/{index}": "Torrent details",
"GET /torrents/{index}/haves": "The bitfield of have pieces",
"GET /torrents/{index}/peer_stats": "Per peer stats",
"GET /torrents/{index}/stats/v1": "Torrent stats",
"GET /web/": "Web UI",
"POST /rust_log": "Set RUST_LOG to this post launch (for debugging)",
"POST /torrents": "Add a torrent here. magnet: or http:// or a local file.",
"POST /torrents/{index}/delete": "Forget about the torrent, remove the files",
"POST /torrents/{index}/forget": "Forget about the torrent, keep the files",
"POST /torrents/{index}/pause": "Pause torrent",
"POST /torrents/{index}/start": "Resume torrent"
},
"server": "rqbit",
"version": "5.4.1"
}
cc @da2ce7
Parent issue: https://github.com/torrust/torrust-tracker/issues/141 It depends on: https://github.com/torrust/torrust-tracker/issues/143
We start building a new API using the
/v2
prefix. For example:/v2/api/stats
. We can use the same URLs but change the response codes.Change the response codes to the right one: 200, 201, 404, etcetera. Right now, it only uses 200 and 500.
Potential changes
I think we could make other changes:
struct Unauthorized
.routes.rs
.authenticate
function should also return a 401 response instead oftoken not valid
when the token is present but not valid.GET /api/torrent/:info_hash
endpoint should return a 404 when the torrent does not exist and the token is valid.GET /api/torrent/:info_hash
should return a 404 when the torrent does not exist, and the token is invalid. See Insecure Direct Object References (IDOR)). We should not expose that the tracker has a given torrent because the tracker could be private.DELETE /api/whitelist/:info_hash
endpoint should return: a "204 No Content" when it deletes the torrent and a "404 Not Found" when the torrent does not exist or the token is invalid.POST /api/whitelist/:info_hash
endpoint should return a "201 Created" response with the location of the new resourceGET /api/whitelist/:info_hash
. In this case we would need to create that new endpoint. It could be empty. It could be used only to know if a torrent is whitelisted. Alternatively, we could consider the whitelist a unique resource and use aPUT /api/whitelist/:info_hash
to add a new torrent to the list.POST /api/key/:seconds_valid
endpoint should return a "201 Created".DELETE /api/key/:key
should return "204 No Content".GET /api/whitelist/reload
endpoint should be aPOST
,PUT
orPATCH
.Notes
Long-term changes
These are changes not included in this issue, but they should be considered in future versions.
GET /api/whitelist/reload
endpoint is a little weird. It's like a remote command. I think I should have usedPOST /api/commands
with the command you want to execute in the request body orPOST /api/reload-whitelist
.GET /api/keys/reload