Endpoints Guide by Jutanium · Pull Request #1638 · withastro/docs

Jutanium · 2022-09-28T19:16:34Z

What kind of changes does this PR include?

New or updated content

Description

Closes New: Add "endpoints" guide #760 and Document all, del, and other possible API route functions #1618
Moves the File Routes content from Astro Pages and the API Routes content from SSR into one page
Renames "file routes" to "static file endpoints" and "api routes" to "server endpoints"
Documents that you can match any HTTP method, that you must use del to match DELETE, and that you can use all to as a catch-all
Fleshes out the buffer PNG example so that it works if you copy-paste it
Show how you can use params and getStaticPaths for static file endpoints (Document getStaticPaths in non-HTML pages #768), explain that props don't do anything here, and that you can access the dynamic parameter without getStaticPaths in SSR mode
Labels the CAPTCHA example as an example, and change the order of the files so that the endpoint is shown before the code that calls it

netlify · 2022-09-28T19:16:41Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`db28e3d`
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/6335e70ce80a210008579d55
😎 Deploy Preview	https://deploy-preview-1638--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

matthewp · 2022-09-28T20:59:01Z

src/pages/en/core-concepts/endpoints.md

@@ -0,0 +1,275 @@
+---
+layout: ~/layouts/MainLayout.astro
+title: Endpoints


I'm totally fine with calling these Endpoints, but just for reference I've also seen them called API Routes. I'm assuming the docs team discussed it and decided on Endpoints, but just in case not, there's another name we've used.

matthewp · 2022-09-28T21:02:23Z

src/pages/en/core-concepts/endpoints.md

+}
+```
+
+This will generate three JSON endpoints at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.


Suggested change

This will generate three JSON endpoints at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.

This will generate three JSON files at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.

Also, for SSG mode we probably could support props, at least I don't see a reason why not. I don't think we excluded that on purpose.

matthewp · 2022-09-28T21:04:13Z

src/pages/en/core-concepts/endpoints.md

+This will generate three JSON endpoints at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.
+
+### `request`
+All endpoints receive a `request` property, but only `request.url` works in static mode. This returns the full URL of the current endpoint, using your [`site`](/en/reference/configuration-reference/#site) config option as the base.


Is this true in dev mode? I would expect that the url is the localhost url during dev.

I would not expect a difference here between endpoints and pages, if there is one it's probably a bug.

matthewp · 2022-09-28T21:06:07Z

src/pages/en/core-concepts/endpoints.md

+Everything in the previous section can be used in SSR mode, but the endpoints will be built when they are requested. This unlocks new features that are unavailable at build time, and allows you to build API routes that listen for requests and securely execute code on the server at runtime.
+
+:::note
+Be sure to [enable SSR](http://localhost:3001/en/guides/server-side-rendering/#enabling-ssr-in-your-project) before trying these examples.


this is pointing to localhost

src/pages/en/core-concepts/endpoints.md

matthewp · 2022-09-28T21:07:21Z

src/pages/en/core-concepts/endpoints.md

+
+```ts title="src/pages/test-post.json.ts"
+export const post: APIRoute = async ({ request }) => {
+  if (request.headers.get("Content-Type") === "application/json") {


good example

matthewp · 2022-09-28T21:07:59Z

src/pages/en/core-concepts/endpoints.md

+```
+
+### Redirects
+Since `Astro.redirect` is not available in API Routes you can use [`Response.redirect`](https://developer.mozilla.org/en-US/docs/Web/API/Response/redirect) to redirect:


This is a bug and something we'll probably be changing, should we document it anyways since it's useful info for now and just remove later?

Yeah, let's document it for now. Is it just Astro.redirect that should be available, or other functions on the Astro global?

sarah11918

Love this page @Jutanium! Made some suggestions for your consideration! ❤️

sarah11918 · 2022-09-28T21:04:55Z

src/pages/en/core-concepts/endpoints.md

+---
+Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.
+
+If your project is in [static](/en/reference/configuration-reference/#output) mode, custom endpoints are called at build time to produce static files. In [SSR](/en/guides/server-side-rendering/) mode, custom endpoints turn into live server endpoints that are called on request. Static and SSR endpoints are defined similarly, but SSR endpoints support additional features.


Suggested change

If your project is in [static](/en/reference/configuration-reference/#output) mode, custom endpoints are called at build time to produce static files. In [SSR](/en/guides/server-side-rendering/) mode, custom endpoints turn into live server endpoints that are called on request. Static and SSR endpoints are defined similarly, but SSR endpoints support additional features.

If your project is in [static](/en/reference/configuration-reference/#output) mode

Do you think this maybe sounds a little "jargony" right off the bat for the regular, default SSG site most people will have? I get that it's the natural counterpart to "SSR/server mode" but I'm not sure we really refer to the "mode" so much when we're talking about our static sites? It's normally only as a way to distinguish from SSR.

Maybe a "friendlier" description here, then "static mode" throughout is probably fine.

In statically-generated sites...

As a default statically-generated site...

I like statically-generated sites, and I rephrased the second sentence to make it clear that static is the default:

In statically-generated sites, your custom endpoints are called at build time to produce static files. If you opt in to [SSR](/en/guides/server-side-rendering/) mode...

Yes, I like that!

sarah11918 · 2022-09-28T21:08:33Z

src/pages/en/core-concepts/endpoints.md

+description: Learn how to create endpoints that serve any kind of data
+i18nReady: true
+---
+Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.


Suggested change

Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.

Astro lets you create custom endpoints (API routes) to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.

Not sure whether even literally just throwing that in there in parenthesis is helpful, but given that a lot of people might be searching for/expecting to see the term API routes, maybe can't hurt to have it somewhere near the very top of the page? Esp. for search results.

Do you think we should do it here, making "API Routes" a synonym for all custom endpoints, and remove the (API Routes) next to Server Endpoints? I was thinking that it was specifically the server version that was previously called API Routes, and the static version we called non-HTML pages (and then file routes).

Or maybe something like

Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or use them as API Routes to build a full API for your site.

What do you think?

I like that!

src/pages/en/core-concepts/endpoints.md

kylebutts · 2022-09-29T00:53:21Z

src/pages/en/core-concepts/endpoints.md

+
+The return object can also have an `encoding` property. It can be any valid [`BufferEncoding`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/bdd02508ddb5eebcf701fdb8ffd6e84eabf47885/types/node/buffer.d.ts#L169) accepted by node.js' `fs.writeFile` method. For example, to produce a binary png image:
+
+```ts title="src/pages/astro-logo.png.ts" {7}


Small highlighting issue, should be {6}

Co-authored-by: Matthew Phillips <matthew@skypack.dev>

Jutanium · 2022-09-29T15:54:48Z

Thanks for the reviews, I've made changes to address the comments!

sarah11918 · 2022-09-29T18:42:08Z

LGTM, Dan! (I'll update branch to make my co-author cred easy. 😉 )

* endpoints draft * fix links * link to endpoints guide from SSR page * request methods -> http methods * api routes -> server endpoints on SSR page * use canonical url * move endpoints in nav to after static assets * Update src/pages/en/core-concepts/endpoints.md Co-authored-by: Matthew Phillips <matthew@skypack.dev> * revision: quick changes * addressed comments Co-authored-by: Matthew Phillips <matthew@skypack.dev> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* i18n(es): add endpoints string for nav.ts * i18n(es): update astro-pages to match #1638 * i18n(es): update broken links Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com>

* 🌐 Updated text from #1638 * Err typo link elem a MDN * 🐛 **Markdown** not worked in md example * ✅ Updated links * ✅ Updated links on `markdown-content.md` * 📝 Readed `Pages non-HTML` part * ✅ Canonical URL * Update src/pages/fr/core-concepts/astro-pages.md Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> * Update src/pages/fr/core-concepts/astro-pages.md Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> * 📝 Edited example of `src/pages/index.astro` in Pages Astro section * 📝 Composant Layouts * 📝 Composants Layout l:45 * 📝 Composants Layout l:63 Co-authored-by: Happydev <81974850+MoustaphaDev@users.noreply.github.com> Co-authored-by: Kevin Zuniga Cuellar <46791833+kevinzunigacuellar@users.noreply.github.com>

* update translation #1442 * update translation #1434 * update translation #1510 * update translation #1538 * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * Update src/content/docs/de/basics/astro-pages.mdx * update translation #1638 * update translation #2091 * update translation #2133 * update translation #2409 * update translation #2371 * update translation #4610 * update translation #5128 * update translation #5205 * update translation #5240 * update translation #5364 * update translation #5765 * update translation #6267 * remove paragraph where I cant find when it was deleted in original version * update translation #6620 * update translation #8495 * update translation #8573 * update translation #9336 * update translation #9336 2/2 didnt save file locally, so git didnt add * fix all visual differences by comparing manually against original english version * fix broken links in `astro-pages.mdx` * Breaking changes to other files! fixing links which link to the �stro-pages.mdx file * but now... * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <51922004+Maxframe@users.noreply.github.com> * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <51922004+Maxframe@users.noreply.github.com> * Update src/content/docs/de/basics/astro-pages.mdx Co-authored-by: Max <51922004+Maxframe@users.noreply.github.com> * revert Update markdown-content.mdx @lunaria-track:src/content/docs/de/basics/astro-pages.mdx --------- Co-authored-by: Max <51922004+Maxframe@users.noreply.github.com> Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>

Dan Jutan added 5 commits September 28, 2022 14:54

endpoints draft

653dcd7

fix links

8201478

link to endpoints guide from SSR page

96aa50f

request methods -> http methods

bf38f02

api routes -> server endpoints on SSR page

a19cc6c

Dan Jutan added 2 commits September 28, 2022 15:24

use canonical url

618ac76

move endpoints in nav to after static assets

1f4ff52

matthewp reviewed Sep 28, 2022

View reviewed changes

src/pages/en/core-concepts/endpoints.md Outdated Show resolved Hide resolved

matthewp reviewed Sep 28, 2022

View reviewed changes

delucis linked an issue Sep 28, 2022 that may be closed by this pull request

Document all, del, and other possible API route functions #1618

Closed

sarah11918 reviewed Sep 28, 2022

View reviewed changes

kylebutts reviewed Sep 29, 2022

View reviewed changes

Dan Jutan and others added 3 commits September 29, 2022 10:21

Update src/pages/en/core-concepts/endpoints.md

55b0439

Co-authored-by: Matthew Phillips <matthew@skypack.dev>

revision: quick changes

5b5e70a

addressed comments

81a2194

Merge branch 'main' into endpoints-guide

db28e3d

thomasbnt mentioned this pull request Oct 1, 2022

i18n(fr) : Updated text for astro-pages in French language #1656

Merged

fredoist mentioned this pull request Oct 2, 2022

i18n(es): update astro-pages.md #1684

Merged

trueberryless added a commit to trueberryless/withastro-docs that referenced this pull request Oct 22, 2024

update translation withastro#1638

1bbeed5

trueberryless mentioned this pull request Oct 22, 2024

i18n(de): update basics/astro-pages.mdx #9759

Merged

	This will generate three JSON endpoints at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.
	This will generate three JSON files at build time: `/api/1.json`, `/api/2.json`, `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages, but because the endpoint is a function and not a component, [props](/en/reference/api-reference/#data-passing-with-props) aren't supported.

	If your project is in [static](/en/reference/configuration-reference/#output) mode, custom endpoints are called at build time to produce static files. In [SSR](/en/guides/server-side-rendering/) mode, custom endpoints turn into live server endpoints that are called on request. Static and SSR endpoints are defined similarly, but SSR endpoints support additional features.
	If your project is in [static](/en/reference/configuration-reference/#output) mode

	Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.
	Astro lets you create custom endpoints (API routes) to serve any kind of data. You can use this to generate images, expose an RSS document, or build a full API for your site.


		The return object can also have an `encoding` property. It can be any valid [`BufferEncoding`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/bdd02508ddb5eebcf701fdb8ffd6e84eabf47885/types/node/buffer.d.ts#L169) accepted by node.js' `fs.writeFile` method. For example, to produce a binary png image:

		```ts title="src/pages/astro-logo.png.ts" {7}

Uh oh!

Conversation

Jutanium commented Sep 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What kind of changes does this PR include?

Description

Uh oh!

netlify bot commented Sep 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jutanium Sep 29, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jutanium commented Sep 29, 2022

Uh oh!

sarah11918 commented Sep 29, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Jutanium commented Sep 28, 2022 •

edited

Loading

netlify bot commented Sep 28, 2022 •

edited

Loading

Jutanium Sep 29, 2022 •

edited

Loading