API overhaul: add version prefix v1 to the API endpoints

src/apis/mod.rs

@@ -1,8 +1,6 @@
-pub mod context;
-pub mod middlewares;
-pub mod responses;
 pub mod routes;
 pub mod server;
+pub mod v1;
 
 use serde::Deserialize;
 

src/apis/routes.rs

@@ -2,18 +2,17 @@ use std::sync::Arc;
 
 use axum::{middleware, Router};
 
-use super::context::{auth_key, stats, torrent, whitelist};
-use super::middlewares::auth::auth;
+use super::v1;
+use super::v1::middlewares::auth::auth;
 use crate::tracker::Tracker;
 
 #[allow(clippy::needless_pass_by_value)]
 pub fn router(tracker: Arc<Tracker>) -> Router {
     let router = Router::new();
 
-    let router = auth_key::routes::add(router, tracker.clone());
-    let router = stats::routes::add(router, tracker.clone());
-    let router = whitelist::routes::add(router, tracker.clone());
-    let router = torrent::routes::add(router, tracker.clone());
+    let prefix = "/api";
+
+    let router = v1::routes::add(prefix, router, tracker.clone());
 
     router.layer(middleware::from_fn_with_state(tracker.config.clone(), auth))
 }

src/apis/context/auth_key/handlers.rs → src/apis/v1/context/auth_key/handlers.rs

@@ -9,8 +9,8 @@ use serde::Deserialize;
 use super::responses::{
     auth_key_response, failed_to_delete_key_response, failed_to_generate_key_response, failed_to_reload_keys_response,
 };
-use crate::apis::context::auth_key::resources::AuthKey;
-use crate::apis::responses::{invalid_auth_key_param_response, ok_response};
+use crate::apis::v1::context::auth_key::resources::AuthKey;
+use crate::apis::v1::responses::{invalid_auth_key_param_response, ok_response};
 use crate::tracker::auth::Key;
 use crate::tracker::Tracker;
 

src/apis/context/auth_key/responses.rs → src/apis/v1/context/auth_key/responses.rs

@@ -3,8 +3,8 @@ use std::error::Error;
 use axum::http::{header, StatusCode};
 use axum::response::{IntoResponse, Response};
 
-use crate::apis::context::auth_key::resources::AuthKey;
-use crate::apis::responses::unhandled_rejection_response;
+use crate::apis::v1::context::auth_key::resources::AuthKey;
+use crate::apis::v1::responses::unhandled_rejection_response;
 
 /// # Panics
 ///

src/apis/context/auth_key/routes.rs → src/apis/v1/context/auth_key/routes.rs

@@ -6,20 +6,20 @@ use axum::Router;
 use super::handlers::{delete_auth_key_handler, generate_auth_key_handler, reload_keys_handler};
 use crate::tracker::Tracker;
 
-pub fn add(router: Router, tracker: Arc<Tracker>) -> Router {
+pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
     // Keys
     router
         .route(
             // code-review: Axum does not allow two routes with the same path but different path variable name.
             // In the new major API version, `seconds_valid` should be a POST form field so that we will have two paths:
-            // POST /api/key
-            // DELETE /api/key/:key
-            "/api/key/:seconds_valid_or_key",
+            // POST /key
+            // DELETE /key/:key
+            &format!("{prefix}/key/:seconds_valid_or_key"),
             post(generate_auth_key_handler)
                 .with_state(tracker.clone())
                 .delete(delete_auth_key_handler)
                 .with_state(tracker.clone()),
         )
         // Keys command
-        .route("/api/keys/reload", get(reload_keys_handler).with_state(tracker))
+        .route(&format!("{prefix}/keys/reload"), get(reload_keys_handler).with_state(tracker))
 }

src/apis/v1/context/stats/routes.rs

@@ -0,0 +1,11 @@
+use std::sync::Arc;
+
+use axum::routing::get;
+use axum::Router;
+
+use super::handlers::get_stats_handler;
+use crate::tracker::Tracker;
+
+pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
+    router.route(&format!("{prefix}/stats"), get(get_stats_handler).with_state(tracker))
+}

src/apis/context/torrent/handlers.rs → src/apis/v1/context/torrent/handlers.rs

@@ -8,7 +8,7 @@ use serde::{de, Deserialize, Deserializer};
 
 use super::resources::torrent::ListItem;
 use super::responses::{torrent_info_response, torrent_list_response, torrent_not_known_response};
-use crate::apis::responses::invalid_info_hash_param_response;
+use crate::apis::v1::responses::invalid_info_hash_param_response;
 use crate::apis::InfoHashParam;
 use crate::protocol::info_hash::InfoHash;
 use crate::tracker::services::torrent::{get_torrent_info, get_torrents, Pagination};

src/apis/context/torrent/resources/torrent.rs → src/apis/v1/context/torrent/resources/torrent.rs

@@ -75,8 +75,8 @@ mod tests {
     use aquatic_udp_protocol::{AnnounceEvent, NumberOfBytes};
 
     use super::Torrent;
-    use crate::apis::context::torrent::resources::peer::Peer;
-    use crate::apis::context::torrent::resources::torrent::ListItem;
+    use crate::apis::v1::context::torrent::resources::peer::Peer;
+    use crate::apis::v1::context::torrent::resources::torrent::ListItem;
     use crate::protocol::clock::DurationSinceUnixEpoch;
     use crate::protocol::info_hash::InfoHash;
     use crate::tracker::peer;

src/apis/context/torrent/routes.rs → src/apis/v1/context/torrent/routes.rs

@@ -6,12 +6,12 @@ use axum::Router;
 use super::handlers::{get_torrent_handler, get_torrents_handler};
 use crate::tracker::Tracker;
 
-pub fn add(router: Router, tracker: Arc<Tracker>) -> Router {
+pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
     // Torrents
     router
         .route(
-            "/api/torrent/:info_hash",
+            &format!("{prefix}/torrent/:info_hash"),
             get(get_torrent_handler).with_state(tracker.clone()),
         )
-        .route("/api/torrents", get(get_torrents_handler).with_state(tracker))
+        .route(&format!("{prefix}/torrents"), get(get_torrents_handler).with_state(tracker))
 }

src/apis/context/whitelist/handlers.rs → src/apis/v1/context/whitelist/handlers.rs

@@ -7,7 +7,7 @@ use axum::response::Response;
 use super::responses::{
     failed_to_reload_whitelist_response, failed_to_remove_torrent_from_whitelist_response, failed_to_whitelist_torrent_response,
 };
-use crate::apis::responses::{invalid_info_hash_param_response, ok_response};
+use crate::apis::v1::responses::{invalid_info_hash_param_response, ok_response};
 use crate::apis::InfoHashParam;
 use crate::protocol::info_hash::InfoHash;
 use crate::tracker::Tracker;

src/apis/context/whitelist/responses.rs → src/apis/v1/context/whitelist/responses.rs

@@ -2,7 +2,7 @@ use std::error::Error;
 
 use axum::response::Response;
 
-use crate::apis::responses::unhandled_rejection_response;
+use crate::apis::v1::responses::unhandled_rejection_response;
 
 #[must_use]
 pub fn failed_to_remove_torrent_from_whitelist_response<E: Error>(e: E) -> Response {

src/apis/context/whitelist/routes.rs → src/apis/v1/context/whitelist/routes.rs

@@ -6,17 +6,19 @@ use axum::Router;
 use super::handlers::{add_torrent_to_whitelist_handler, reload_whitelist_handler, remove_torrent_from_whitelist_handler};
 use crate::tracker::Tracker;
 
-pub fn add(router: Router, tracker: Arc<Tracker>) -> Router {
+pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
+    let prefix = format!("{prefix}/whitelist");
+
     router
         // Whitelisted torrents
         .route(
-            "/api/whitelist/:info_hash",
+            &format!("{prefix}/:info_hash"),
             post(add_torrent_to_whitelist_handler).with_state(tracker.clone()),
         )
         .route(
-            "/api/whitelist/:info_hash",
+            &format!("{prefix}/:info_hash"),
             delete(remove_torrent_from_whitelist_handler).with_state(tracker.clone()),
         )
         // Whitelist commands
-        .route("/api/whitelist/reload", get(reload_whitelist_handler).with_state(tracker))
+        .route(&format!("{prefix}/reload"), get(reload_whitelist_handler).with_state(tracker))
 }

src/apis/middlewares/auth.rs → src/apis/v1/middlewares/auth.rs

@@ -7,7 +7,7 @@ use axum::response::{IntoResponse, Response};
 use serde::Deserialize;
 use torrust_tracker_configuration::{Configuration, HttpApi};
 
-use crate::apis::responses::unhandled_rejection_response;
+use crate::apis::v1::responses::unhandled_rejection_response;
 
 #[derive(Deserialize, Debug)]
 pub struct QueryParams {

src/apis/v1/mod.rs

@@ -0,0 +1,4 @@
+pub mod context;
+pub mod middlewares;
+pub mod responses;
+pub mod routes;

src/apis/v1/routes.rs

@@ -0,0 +1,23 @@
+use std::sync::Arc;
+
+use axum::Router;
+
+use super::context::{auth_key, stats, torrent, whitelist};
+use crate::tracker::Tracker;
+
+pub fn add(prefix: &str, router: Router, tracker: Arc<Tracker>) -> Router {
+    // Without `v1` prefix.
+    // We keep the old API endpoints without `v1` prefix for backward compatibility.
+    // todo: remove when the torrust index backend is using the `v1` prefix.
+    let router = auth_key::routes::add(prefix, router, tracker.clone());
+    let router = stats::routes::add(prefix, router, tracker.clone());
+    let router = whitelist::routes::add(prefix, router, tracker.clone());
+    let router = torrent::routes::add(prefix, router, tracker.clone());
+
+    // With `v1` prefix
+    let v1_prefix = format!("{prefix}/v1");
+    let router = auth_key::routes::add(&v1_prefix, router, tracker.clone());
+    let router = stats::routes::add(&v1_prefix, router, tracker.clone());
+    let router = whitelist::routes::add(&v1_prefix, router, tracker.clone());
+    torrent::routes::add(&v1_prefix, router, tracker)
+}