From f5a7480f699590f4534627b36ff927d4cb719c08 Mon Sep 17 00:00:00 2001
From: Valerio Ageno <51341197+Valerioageno@users.noreply.github.com>
Date: Fri, 7 Feb 2025 19:07:58 +0100
Subject: [PATCH] docs: add API routes page (#528)

Co-authored-by: Marco Pasqualetti <24919330+marcalexiei@users.noreply.github.com>
---
 .../src/components/Sidebar/sidebarElements.ts |  5 ++
 .../documentation/routing/api-routes.mdx      | 66 +++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 apps/documentation/src/routes/documentation/routing/api-routes.mdx

diff --git a/apps/documentation/src/components/Sidebar/sidebarElements.ts b/apps/documentation/src/components/Sidebar/sidebarElements.ts
index 7b8124ba..ae01b2ff 100644
--- a/apps/documentation/src/components/Sidebar/sidebarElements.ts
+++ b/apps/documentation/src/components/Sidebar/sidebarElements.ts
@@ -121,6 +121,11 @@ export const sidebarElements: Array<SidebarElement> = [
         label: 'Link and navigation',
         href: '/documentation/routing/link-and-navigation',
       },
+      {
+        type: 'element',
+        label: 'API routes',
+        href: '/documentation/routing/api-routes',
+      },
     ],
   },
   {
diff --git a/apps/documentation/src/routes/documentation/routing/api-routes.mdx b/apps/documentation/src/routes/documentation/routing/api-routes.mdx
new file mode 100644
index 00000000..bbc6ef53
--- /dev/null
+++ b/apps/documentation/src/routes/documentation/routing/api-routes.mdx
@@ -0,0 +1,66 @@
+import MetaTags from '@/components/MetaTags'
+
+<MetaTags
+  title="Tuono - API routes"
+  canonical="https://tuono.dev/documentation/routing/api-routes"
+/>
+
+import Breadcrumbs from '@/components/Breadcrumbs'
+
+<Breadcrumbs breadcrumbs={[{ label: 'API routes' }]} />
+
+# API routes
+
+## Overview
+
+API routes offer a solution for building a public API using Tuono.
+
+Any file inside the `src/routes/api` folder is mapped to the `/api/*` path
+and will be treated as an API endpoint, rather than a React route.
+
+Tuono server is internally managed by [axum](https://docs.rs/axum/latest/axum/).
+The API system allows you to create APIs using most of the axum syntax.
+Tuono re-exports axum `tuono_lib::axum::*` to be seamlessly used within any Tuono app.
+
+The major differences are:
+
+- The function to be matched with Tuono's file system routing must have the
+  `tuono_lib::api(method)` macro attribute on top of it.
+- The first argument of the function is always a `tuono_lib::Request`.
+
+Tuono also supports [dynamic routes](/documentation/routing/dynamic-routes) for APIs.
+
+## Example
+
+If you create `src/routes/api/books.rs` with the following content,
+any HTTP GET request to `/api/books` will return a list of the queried books as JSON.
+
+```rs
+use tuono_lib::Request;
+use tuono_lib::axum::response::IntoResponse;
+
+use serde_json::{Value, json};
+
+#[tuono_lib::api(GET)]
+async fn book_list(req: Request) -> Json<Value> {
+  let books = get_books_from_db().await;
+
+  Json(json!(books))
+}
+```
+
+> Unlike React routes, API must not return `tuono_lib::Response`
+
+The same file can contain multiple HTTP methods.
+
+```rs
+#[tuono_lib::api(GET)]
+async fn get_book_list(req: Request) -> Json<Value> {
+  //...
+}
+
+#[tuono_lib::api(POST)]
+async fn add_book_to_library(req: Request) -> impl IntoResponse {
+  //...
+}
+```