You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/docs/01-routing.md
+24-22Lines changed: 24 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,9 +45,7 @@ A file or directory can have multiple dynamic parts, like `[id]-[category].svelt
45
45
46
46
### Endpoints
47
47
48
-
Endpoints are modules written in `.js` (or `.ts`) files that export functions corresponding to HTTP methods. Their job is to allow pages to read and write data that is only available on the server (for example in a database, or on the filesystem).
49
-
50
-
If an endpoint has the same filename as a page (except for the extension), the page will get its props from the endpoint. So a page like `src/routes/items/[id].svelte` could get its props from this file:
48
+
Endpoints are modules written in `.js` (or `.ts`) files that export [request handler](/docs/types#sveltejs-kit-requesthandler) functions corresponding to HTTP methods. Their job is to make it possible to read and write data that is only available on the server (for example in a database, or on the filesystem).
> All server-side code, including endpoints, has access to `fetch` in case you need to request data from external APIs. Don't worry about the `$lib` import, we'll get to that [later](/docs/modules#$lib).
83
81
84
-
The job of this function is to return a `{ status, headers, body }` object representing the response, where `status` is an [HTTP status code](https://httpstatusdogs.com):
82
+
The job of a [request handler](/docs/types#sveltejs-kit-requesthandler) is to return a `{ status, headers, body }` object representing the response, where `status` is an [HTTP status code](https://httpstatusdogs.com):
85
83
86
84
-`2xx` — successful response (default is `200`)
87
85
-`3xx` — redirection (should be accompanied by a `location` header)
@@ -90,7 +88,11 @@ The job of this function is to return a `{ status, headers, body }` object repre
90
88
91
89
> If `{fallthrough: true}` is returned SvelteKit will [fall through](/docs/routing#advanced-routing-fallthrough-routes) to other routes until something responds, or will respond with a generic 404.
92
90
93
-
The returned `body` corresponds to the page's props:
91
+
#### Page endpoints
92
+
93
+
If an endpoint has the same filename as a page (except for the extension), the page gets its props from the endpoint — via `fetch` during client-side navigation, or via direct function call during SSR.
94
+
95
+
A page like `src/routes/items/[id].svelte` could get its props from the `body` in the endpoint above:
94
96
95
97
```svelte
96
98
/// file: src/routes/items/[id].svelte
@@ -102,6 +104,23 @@ The returned `body` corresponds to the page's props:
102
104
<h1>{item.title}</h1>
103
105
```
104
106
107
+
Because the page and route have the same URL, you will need to include an `accept: application/json` header to get JSON from the endpoint rather than HTML from the page. You can also get the raw data by appending `/__data.json` to the URL, e.g. `/items/__data.json`.
108
+
109
+
#### Standalone endpoints
110
+
111
+
Most commonly, endpoints exist to provide data to the page with which they're paired. They can, however, exist separately from pages. Standalone endpoints have slightly more flexibility over the returned `body` type — in addition to objects, they can return a `Uint8Array`.
112
+
113
+
Standalone endpoints can be given a file extension if desired, or accessed directly if not:
114
+
115
+
| filename | endpoint |
116
+
| ----------------------------- | ---------- |
117
+
| src/routes/data/index.json.js | /data.json |
118
+
| src/routes/data.json.js | /data.json |
119
+
| src/routes/data/index.js | /data |
120
+
| src/routes/data.js | /data |
121
+
122
+
> Support for streaming request and response bodies is [coming soon](https://github.com/sveltejs/kit/issues/3419).
123
+
105
124
#### POST, PUT, PATCH, DELETE
106
125
107
126
Endpoints can handle any HTTP method — not just `GET` — by exporting the corresponding function:
If you request the route with an `accept: application/json` header, SvelteKit will render the endpoint data as JSON, rather than the page as HTML. You can also get the raw data by appending `/__data.json` to the URL, e.g. `/items/__data.json`.
195
-
196
213
#### Body parsing
197
214
198
215
The `request` object is an instance of the standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) class. As such, accessing the request body is easy:
@@ -263,21 +280,6 @@ export default config;
263
280
264
281
> Using native `<form>` behaviour ensures your app continues to work when JavaScript fails or is disabled.
265
282
266
-
### Standalone endpoints
267
-
268
-
Most commonly, endpoints exist to provide data to the page with which they're paired. They can, however, exist separately from pages. Standalone endpoints have slightly more flexibility over the returned `body` type — in addition to objects, they can return a string or a `Uint8Array`.
269
-
270
-
> Support for streaming request and response bodies is [coming soon](https://github.com/sveltejs/kit/issues/3419).
271
-
272
-
Standalone endpoints can be given a file extension if desired, or accessed directly if not:
273
-
274
-
| filename | endpoint |
275
-
| ----------------------------- | ---------- |
276
-
| src/routes/data/index.json.js | /data.json |
277
-
| src/routes/data.json.js | /data.json |
278
-
| src/routes/data/index.js | /data |
279
-
| src/routes/data.js | /data |
280
-
281
283
### Private modules
282
284
283
285
Files and directories with a leading `_` or `.` (other than [`.well-known`](https://en.wikipedia.org/wiki/Well-known_URI)) are private by default, meaning that they do not create routes (but can be imported by files that do). You can configure which modules are considered public or private with the [`routes`](/docs/configuration#routes) configuration.
0 commit comments