|
| 1 | +--- |
| 2 | +sidebar_position: 1 |
| 3 | +--- |
| 4 | + |
| 5 | +# Endpoint Routing |
| 6 | + |
| 7 | +This guide will walk you through creating your first endpoints in Yelix. Endpoints are the building blocks of your API, defining how your application responds to HTTP requests. |
| 8 | + |
| 9 | +## Simple endpoint that returns text |
| 10 | + |
| 11 | +Creating a basic endpoint in Yelix is straightforward. Below is an example of a simple endpoint that returns plain text with a 200 OK status code. The `ctx.text()` method is used to send text responses back to the client. |
| 12 | + |
| 13 | +```ts title="hello.ts" |
| 14 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 15 | + |
| 16 | +export async function GET(ctx: Ctx) { |
| 17 | + // highlight-next-line |
| 18 | + return await ctx.text('Hello World!', 200); |
| 19 | +} |
| 20 | + |
| 21 | +export const path = '/api/hello'; |
| 22 | +``` |
| 23 | + |
| 24 | +## Return JSON |
| 25 | + |
| 26 | +Most modern APIs communicate using JSON. Yelix makes it easy to return JSON responses using the `ctx.json()` method. This automatically sets the appropriate content type headers for you. |
| 27 | + |
| 28 | +```ts title="hello.ts" |
| 29 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 30 | + |
| 31 | +export async function GET(ctx: Ctx) { |
| 32 | + // highlight-next-line |
| 33 | + return await ctx.json({ message: 'Hello World!' }, 200); |
| 34 | +} |
| 35 | + |
| 36 | +export const path = '/api/hello'; |
| 37 | +``` |
| 38 | + |
| 39 | +## Return HTML |
| 40 | + |
| 41 | +For endpoints that need to return HTML content, use the `ctx.html()` method. This sets the content type to 'text/html' and returns your HTML string to the client. |
| 42 | + |
| 43 | +```ts title="hello.ts" |
| 44 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 45 | + |
| 46 | +export async function GET(ctx: Ctx) { |
| 47 | + // highlight-next-line |
| 48 | + return await ctx.html('<h1>Hello World!</h1>', 200); |
| 49 | +} |
| 50 | + |
| 51 | +export const path = '/api/hello'; |
| 52 | +``` |
| 53 | + |
| 54 | +## HTTP Methods |
| 55 | + |
| 56 | +Yelix supports all standard HTTP methods. You can define handlers for different methods on the same route by exporting functions named after the HTTP method. This allows you to implement RESTful API patterns easily. |
| 57 | + |
| 58 | +```ts title="hello.ts" |
| 59 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 60 | + |
| 61 | +export async function GET(ctx: Ctx) { return await ctx.text('Hello World!', 200); } |
| 62 | +export async function POST(ctx: Ctx) { return await ctx.text('Hello World!', 200); } |
| 63 | +export async function PUT(ctx: Ctx) { return await ctx.text('Hello World!', 200); } |
| 64 | +export async function DELETE(ctx: Ctx) { return await ctx.text('Hello World!', 200); } |
| 65 | + |
| 66 | +export const path = '/api/hello'; |
| 67 | +``` |
| 68 | + |
| 69 | +## Path Parameter |
| 70 | + |
| 71 | +Dynamic routes are essential for building flexible APIs. Yelix allows you to define path parameters using the `:parameter` syntax in your route definition. You can then access these parameters in your handler using `ctx.req.param()`. |
| 72 | + |
| 73 | +```ts title="hello.ts" |
| 74 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 75 | + |
| 76 | +export async function GET(ctx: Ctx) { |
| 77 | + // highlight-next-line |
| 78 | + const name = ctx.req.param('name') |
| 79 | + |
| 80 | + return await ctx.json({ message: 'Hello World!' }, 200); |
| 81 | +} |
| 82 | + |
| 83 | +// highlight-next-line |
| 84 | +export const path = '/api/user/:name'; |
| 85 | +``` |
| 86 | + |
| 87 | +or all parameters at once: |
| 88 | + |
| 89 | +```ts title="hello.ts" |
| 90 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 91 | + |
| 92 | +export async function GET(ctx: Ctx) { |
| 93 | + // highlight-next-line |
| 94 | + const { id, comment_id } = ctx.req.param() |
| 95 | + |
| 96 | + return await ctx.json({ message: 'Hello World!' }, 200); |
| 97 | +} |
| 98 | + |
| 99 | +// highlight-next-line |
| 100 | +export const path = '/api/posts/:id/comment/:comment_id'; |
| 101 | +``` |
| 102 | + |
| 103 | +## Optional Parameter |
| 104 | + |
| 105 | +Sometimes you want a parameter to be optional. Yelix supports this by adding a `?` after the parameter name. This means the route will match both with and without the parameter specified. |
| 106 | + |
| 107 | +```ts title="hello.ts" |
| 108 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 109 | + |
| 110 | +export async function GET(ctx: Ctx) { |
| 111 | + // highlight-next-line |
| 112 | + const name = ctx.req.param('name') |
| 113 | + |
| 114 | + return await ctx.json({ message: 'Hello World!' }, 200); |
| 115 | +} |
| 116 | + |
| 117 | +// Will match /api/user/murat and /api/user |
| 118 | +// highlight-next-line |
| 119 | +export const path = '/api/user/:name?'; |
| 120 | +``` |
| 121 | + |
| 122 | +## Regular Expressions |
| 123 | + |
| 124 | +For more advanced routing needs, you can use regular expressions to constrain path parameters. This is useful when you need to ensure parameters match a specific format, such as numbers or specific text patterns. |
| 125 | + |
| 126 | +```ts title="hello.ts" |
| 127 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 128 | + |
| 129 | +export async function GET(ctx: Ctx) { |
| 130 | + const { date, title } = ctx.req.param() |
| 131 | + |
| 132 | + return await ctx.text('Hello World!', 200); |
| 133 | +} |
| 134 | + |
| 135 | +// highlight-next-line |
| 136 | +export const path = '/api/post/:date{[0-9]+}/:title{[a-z]+}'; |
| 137 | +``` |
| 138 | + |
| 139 | +## Including slashes |
| 140 | + |
| 141 | +By default, path parameters don't match slashes to prevent accidentally capturing too much of the URL. However, sometimes you need to match paths that include slashes, such as file paths. You can use a custom regex pattern to achieve this. |
| 142 | + |
| 143 | +```ts title="hello.ts" |
| 144 | +import type { Ctx } from "jsr:@murat/yelix"; |
| 145 | + |
| 146 | +export async function GET(ctx: Ctx) { |
| 147 | + const { filename } = ctx.req.param() |
| 148 | + |
| 149 | + return await ctx.text('Hello World!', 200); |
| 150 | +} |
| 151 | + |
| 152 | +// highlight-next-line |
| 153 | +export const path = '/api/posts/:filename{.+\\.png}'; |
| 154 | +``` |
0 commit comments