docs(plugin-api): update to v8 (#293)

docs/Guide/plugins/API/adding-routes.mdx

@@ -3,24 +3,13 @@ title: How to add routes
 sidebar_position: 1
 ---
 
-First we create a new folder called `routes` in the `src` directory. And make a new file `hello-world`
+First we create a new folder called `routes` in the `src` directory. And make a new file `hello-world.get`
 
 ```typescript ts2esm2cjs
-import { methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { Route } from '@sapphire/plugin-api';
 
 export class UserRoute extends Route {
-  public constructor(context: Route.LoaderContext, options: Route.Options) {
-    super(context, {
-      ...options,
-      route: 'hello-world'
-    });
-  }
-
-  public [methods.GET](_request: ApiRequest, response: ApiResponse) {
-    response.json({ message: 'Hello World' });
-  }
-
-  public [methods.POST](_request: ApiRequest, response: ApiResponse) {
+  public run(_request: Route.Request, response: Route.Response) {
     response.json({ message: 'Hello World' });
   }
 }
@@ -29,6 +18,5 @@ export class UserRoute extends Route {
 A quick glance on what we did above:
 
 - First we extended the `Route` class to make our route
-- Second we specified the route name in the constructor
-- Third we defined the GET method
-- Finally we responded to the request with a message which we would be able to use later when we fetch the route
+- Second we defined the handler for the `GET` method defined in the filename
+- Finally, when `GET /hello-world` is called, the route will reply with the defined body

docs/Guide/plugins/API/authenticating-routes.mdx

@@ -13,11 +13,11 @@ if [`request.auth.token`][request-auth-token] is defined or not. When it is not,
 `401 Unauthorized` response.
 
 ```typescript ts2esm2cjs|{6,8}|{6,8}
-import { HttpCodes, methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { HttpCodes, Route } from '@sapphire/plugin-api';
 import { isNullishOrEmpty } from '@sapphire/utilities';
 
 export class MyRoute extends Route {
-  public async [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     if (isNullishOrEmpty(request.auth?.token)) return response.error(HttpCodes.Unauthorized);
   }
 }
@@ -29,23 +29,23 @@ decorator. A decorator that does the authentication check can look like:
 
 ```typescript ts2esm2cjs|{{4-8}}|{{4-8}}
 import { createFunctionPrecondition } from '@sapphire/decorators';
-import { ApiRequest, ApiResponse, HttpCodes } from '@sapphire/plugin-api';
+import { HttpCodes, type Route } from '@sapphire/plugin-api';
 
 export const authenticated = () =>
   createFunctionPrecondition(
-    (request: ApiRequest) => Boolean(request.auth?.token),
-    (_request: ApiRequest, response: ApiResponse) => response.error(HttpCodes.Unauthorized)
+    (request: Route.Request) => Boolean(request.auth?.token),
+    (_request: Route.Request, response: Route.Response) => response.error(HttpCodes.Unauthorized)
   );
 ```
 
 You can then use the decorator on your route like so:
 
 ```typescript {4} showLineNumbers
-import { methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { Route } from '@sapphire/plugin-api';
 
 export class MyRoute extends Route {
   @authenticated()
-  public [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     // Implementation
   }
 }

docs/Guide/plugins/API/oauth2-refresh-token.mdx

@@ -20,14 +20,14 @@ limits to routes][rate-limiting].
 ## Implementing the refresh route
 
 The first step is to add a new route, more information for adding routes can be found in the [Adding
-routes][adding-routes] page. For the rest of this guide we will assume the route is `/oauth/refresh` as path. Lets start
-by writing the basics:
+routes][adding-routes] page. For the rest of this guide we will assume the route is `/oauth/refresh.post` as path. Lets
+start by writing the basics:
 
 ```typescript ts2esm2cjs|{4-6}
-import { methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { methods, Route } from '@sapphire/plugin-api';
 
 export class RefreshRoute extends Route {
-  public async [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     // implementation
   }
 }
@@ -40,10 +40,10 @@ In this part of the code we also extract some nested variables into local variab
 later.
 
 ```typescript ts2esm2cjs|{5-10}
-import { HttpCodes, methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { HttpCodes, Route } from '@sapphire/plugin-api';
 
 export class RefreshRoute extends Route {
-  public async [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     if (!request.auth) return response.error(HttpCodes.Unauthorized);
 
     const requestAuth = request.auth;
@@ -75,13 +75,13 @@ refresh the token, and add the new token as a cookie to the response:
 
 ```typescript ts2esm2cjs|{16-30,33-59}|{16-30,33-59}
 import { fetch, FetchResultTypes } from '@sapphire/fetch';
-import { HttpCodes, methods, MimeTypes, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { HttpCodes, MimeTypes, Route } from '@sapphire/plugin-api';
 import { Time } from '@sapphire/time-utilities';
 import { OAuth2Routes, type RESTPostOAuth2AccessTokenResult } from 'discord.js';
 import { stringify } from 'node:querystring';
 
 export class RefreshRoute extends Route {
-  public async [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     if (!request.auth) return response.error(HttpCodes.Unauthorized);
 
     const requestAuth = request.auth;
@@ -167,7 +167,7 @@ import { OAuth2Routes, type RESTPostOAuth2AccessTokenResult } from 'discord.js';
 import { stringify } from 'node:querystring';
 
 export class RefreshRoute extends Route {
-  public async [methods.POST](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     if (!request.auth) return response.error(HttpCodes.Unauthorized);
 
     const requestAuth = request.auth;

docs/Guide/plugins/API/rate-limiting.mdx

@@ -10,24 +10,16 @@ by a large number of users. On this page we will guide you to write your own rat
 The first step to creating a rate limiter is create an instance of `RateLimitManager`. This manager has to be created on
 a per-route basis, so it is advisable to create it as a class property or constant in the file of the route.
 
-```typescript ts2esm2cjs|{6,8}|{6,8}
-import { methods, Route } from '@sapphire/plugin-api';
+```typescript ts2esm2cjs|{5,6}|{5,6}
+import { Route } from '@sapphire/plugin-api';
 import { Time } from '@sapphire/time-utilities';
 import { RateLimitManager } from '@sapphire/ratelimits';
 
 export class UserRoute extends Route {
-  private timeForRateLimit = Time.Second * 5;
-
+  private readonly timeForRateLimit = Time.Second * 5;
   private readonly rateLimitManager = new RateLimitManager(Time.Second * 5, 1);
 
-  public constructor(context: Route.LoaderContext, options: Route.Options) {
-    super(context, {
-      ...options,
-      route: 'hello-world'
-    });
-  }
-
-  public [methods.GET](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     response.json({ message: 'Hello World' });
   }
 }
@@ -106,25 +98,17 @@ in an `if` check in the route to change the response behaviour, as seen below.
 
 Finally we can put this all together:
 
-```typescript ts2esm2cjs|{19-28}
-import { ApiRequest, ApiResponse, HttpCodes, methods, Route } from '@sapphire/plugin-api';
+```typescript ts2esm2cjs|{10-19}
+import { HttpCodes, Route } from '@sapphire/plugin-api';
 import { Time } from '@sapphire/time-utilities';
 import { RateLimitManager } from '@sapphire/ratelimits';
 import { isRateLimited } from '../lib/api/utils'; // Example, you can put the function anywhere you want.
 
 export class UserRoute extends Route {
-  private timeForRateLimit = Time.Second * 5;
-
+  private readonly timeForRateLimit = Time.Second * 5;
   private readonly rateLimitManager = new RateLimitManager(Time.Second * 5, 1);
 
-  public constructor(context: Route.LoaderContext, options: Route.Options) {
-    super(context, {
-      ...options,
-      route: 'hello-world'
-    });
-  }
-
-  public [methods.GET](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     if (
       isRateLimited({
         time: this.timeForRateLimit,

docs/Guide/plugins/API/returning-data.mdx

@@ -7,10 +7,10 @@ Sapphire offers a custom [`ApiResponse`] with useful methods for returning data.
 to return JSON data with a status of 200 (OK):
 
 ```typescript ts2esm2cjs|{5-7}
-import { methods, Route, type ApiRequest, type ApiResponse } from '@sapphire/plugin-api';
+import { Route } from '@sapphire/plugin-api';
 
 export class MyRoute extends Route {
-  public [methods.GET](request: ApiRequest, response: ApiResponse) {
+  public async run(request: Route.Request, response: Route.Response) {
     return response.json({
       myBestFriend: 'Sapphire'
     });