docs: Add documentation for Serverpod 3 WebServer"

docs/06-concepts/06-database/09-pagination.md

@@ -1,110 +0,0 @@
-# Pagination
-
-Serverpod provides built-in support for pagination to help manage large datasets, allowing you to retrieve data in smaller chunks. Pagination is achieved using the `limit` and `offset` parameters.
-
-## Limit
-
-The `limit` parameter specifies the maximum number of records to return from the query. This is equivalent to the number of rows on a page.
-
-```dart
-var companies = await Company.db.find(
-  session,
-  limit: 10,
-);
-```
-
-In the example we fetch the first 10 companies.
-
-## Offset
-
-The `offset` parameter determines the starting point from which to retrieve records. It essentially skips the first `n` records.
-
-```dart
-var companies = await Company.db.find(
-  session,
-  limit: 10,
-  offset: 30,
-);
-```
-
-In the example we skip the first 30 rows and fetch the 31st to 40th company.
-
-## Using limit and offset for pagination
-
-Together, `limit` and `offset` can be used to implement pagination.
-
-```dart
-int page = 3;
-int companiesPerPage = 10;
-
-var companies = await Company.db.find(
-  session,
-  orderBy: (t) => t.id,
-  limit: companiesPerPage,
-  offset: (page - 1) * companiesPerPage,
-);
-```
-
-In the example we fetch the third page of companies, with 10 companies per page.
-
-### Tips
-
-1. **Performance**: Be aware that while `offset` can help in pagination, it may not be the most efficient way for very large datasets. Using an indexed column to filter results can sometimes be more performant.
-2. **Consistency**: Due to possible data changes between paginated requests (like additions or deletions), the order of results might vary. It's recommended to use an `orderBy` parameter to ensure consistency across paginated results.
-3. **Page numbering**: Page numbers usually start from 1. Adjust the offset calculation accordingly.
-
-## Cursor-based pagination
-
-A limit-offset pagination may not be the best solution if the table is changed frequently and rows are added or removed between requests.
-
-Cursor-based pagination is an alternative method to the traditional limit-offset pagination. Instead of using an arbitrary offset to skip records, cursor-based pagination uses a unique record identifier (a _cursor_) to mark the starting or ending point of a dataset. This approach is particularly beneficial for large datasets as it offers consistent and efficient paginated results, even if the data is being updated frequently.
-
-### How it works
-
-In cursor-based pagination, the client provides a cursor as a reference point, and the server returns data relative to that cursor. This cursor is usually an `id`.
-
-### Implementing cursor-based pagination
-
-1. **Initial request**:
-    For the initial request, where no cursor is provided, retrieve the first `n` records:
-
-    ```dart
-    int recordsPerPage = 10;
-
-    var companies = await Company.db.find(
-    session,
-    orderBy: (t) => t.id,
-    limit: recordsPerPage,
-    );
-    ```
-
-2. **Subsequent requests**:
-    For the subsequent requests, use the cursor (for example, the last `id` from the previous result) to fetch the next set of records:
-
-    ```dart
-    int cursor = lastCompanyIdFromPreviousPage; // This is typically sent by the client
-
-    var companies = await Company.db.find(
-    session,
-    where: Company.t.id > cursor,
-    orderBy: (t) => t.id,
-    limit: recordsPerPage,
-    );
-    ```
-
-3. **Returning the cursor**:
-    When returning data to the client, also return the cursor, so it can be used to compute the starting point for the next page.
-
-    ```dart
-    return {
-    'data': companies,
-    'lastCursor': companies.last.id,
-    };
-    ```
-
-### Tips
-
-1. **Choosing a cursor**: While IDs are commonly used as cursors, timestamps or other unique, sequentially ordered fields can also serve as effective cursors.
-2. **Backward pagination**: To implement backward pagination, use the first item from the current page as the cursor and adjust the query accordingly.
-3. **Combining with sorting**: Ensure the field used as a cursor aligns with the sorting order. For instance, if you're sorting data by a timestamp in descending order, the cursor should also be based on the timestamp.
-4. **End of data**: If the returned data contains fewer items than the requested limit, it indicates that you've reached the end of the dataset.

docs/06-concepts/18-webserver/01-overview.md

@@ -0,0 +1,154 @@
+# Overview
+
+In addition to the application server, Serverpod comes with a built-in web server. The web server allows you to access your database and business layer the same way you would from a method call from an app. This makes it simple to share data for applications that need both an app and traditional web pages. You can also use the web server to create webhooks or define custom REST APIs to communicate with third-party services.
+
+Serverpod's web server is built on the [Relic](https://github.com/serverpod/relic) framework, giving you access to its routing engine, middleware system, and typed headers. This means you get the benefits of Serverpod's database integration and business logic alongside Relic's web server capabilities.
+
+## Your first route
+
+When you create a new Serverpod project, it sets up a web server by default. Here's how to add a simple API endpoint:
+
+```dart
+import 'package:serverpod/serverpod.dart';
+
+class HelloRoute extends Route {
+  @override
+  Future<Result> handleCall(Session session, Request request) async {
+    return Response.ok(
+      body: Body.fromString(
+        jsonEncode({'message': 'Hello from Serverpod!'}),
+        mimeType: MimeType.json,
+      ),
+    );
+  }
+}
+```
+
+Register the route in your `server.dart` file before starting the server:
+
+```dart
+pod.webServer.addRoute(HelloRoute(), '/api/hello');
+await pod.start();
+```
+
+Visit `http://localhost:8080/api/hello` to see your API response.
+
+## Core concepts
+
+### Routes and handlers
+
+A **Route** is a destination in your web server that handles requests and generates responses. Routes extend the `Route` base class and implement the `handleCall()` method:
+
+```dart
+class ApiRoute extends Route {
+  @override
+  Future<Result> handleCall(Session session, Request request) async {
+    // Your logic here
+    return Response.ok();
+  }
+}
+```
+
+The `handleCall()` method receives:
+
+- **Session** - Access to your database, logging, and authenticated user
+- **Request** - The HTTP request with headers, body, and URL information
+
+### Response types
+
+Return different response types based on your needs:
+
+```dart
+// Success responses
+return Response.ok(body: Body.fromString('Success'));
+return Response.created(body: Body.fromString('Created'));
+return Response.noContent();
+
+// Error responses
+return Response.badRequest(body: Body.fromString('Invalid input'));
+return Response.unauthorized(body: Body.fromString('Not authenticated'));
+return Response.notFound(body: Body.fromString('Not found'));
+return Response.internalServerError(body: Body.fromString('Server error'));
+```
+
+### Adding routes
+
+Routes are added with a path pattern:
+
+```dart
+// Exact path
+pod.webServer.addRoute(UserRoute(), '/api/users');
+
+// Path with wildcard
+pod.webServer.addRoute(StaticRoute.directory(Directory('web')), '/static/**');
+```
+
+Routes are matched in the order they were added.
+
+## When to use what
+
+### Rest apis → custom routes
+
+For REST APIs, webhooks, or custom HTTP handlers, use custom `Route` classes:
+
+```dart
+class UsersApiRoute extends Route {
+  UsersApiRoute() : super(methods: {Method.get, Method.post});
+
+  @override
+  Future<Result> handleCall(Session session, Request request) async {
+    if (request.method == Method.get) {
+      // List users
+    } else {
+      // Create user
+    }
+  }
+}
+```
+
+See [Routing](routing) for details.
+
+### Static files → `StaticRoute`
+
+For serving CSS, JavaScript, images, or other static assets:
+
+```dart
+pod.webServer.addRoute(
+  StaticRoute.directory(Directory('web/static')),
+  '/static/**',
+);
+```
+
+See [Static Files](static-files) for cache-busting and optimization.
+
+## Database access
+
+The `Session` parameter gives you full access to your Serverpod database:
+
+```dart
+class UserRoute extends Route {
+  @override
+  Future<Result> handleCall(Session session, Request request) async {
+    // Query database
+    final users = await User.db.find(session);
+
+    // Use logging
+    session.log('Retrieved ${users.length} users');
+
+    return Response.ok(
+      body: Body.fromString(
+        jsonEncode(users.map((u) => u.toJson()).toList()),
+        mimeType: MimeType.json,
+      ),
+    );
+  }
+}
+```
+
+## Next steps
+
+- **[Routing](routing)** - Match requests to handlers by method and URL pattern
+- **[Request Data](request-data)** - Access path parameters, query parameters, headers, and body
+- **[Middleware](middleware)** - Intercept and transform requests and responses
+- **[Static Files](static-files)** - Serve static assets
+- **[Server-side HTML](server-side-html)** - Render HTML dynamically on the server