New: Add "endpoints" guide

[bholmesdev]

Our guides for creating non-HTML pages (aka "endpoints") are pretty tough to scan as a new user. Right now, we have:

• "non-HTML pages" listed on our pages docs, which I can't find by searching for "endpoint" 😕
• the "response" section at the bottom of our SSR docs; again, not find-able searching for "endpoint"

☝️ We also have different advice for endpoint return values for SSG vs. SSR. In SSR, we recommend a formatted Response object with a defined content type. In SSG, you must use a { body } object only (Response will break during builds) to output a static file. This speaks to a more fundamental issue with SSR, where it's more tacked-on than interwoven with our existing docs.

Solution: a general "endpoints" docs page would be an excellent landing spot to compare SSG and SSR approaches to non-HTML files. We are beginning to encourage .js endpoints for any clientside data fetching as well, so a dedicated page for the concept should aid in onboarding SSR users.

[delucis]

I opened #768 for this related content, but it might make sense to roll it up into this one, so pasting this here and we can tackle it together.

---

Non-HTML pages support exporting a getStaticPaths function just like .astro dynamic routes do, but we don’t currently document it. This should at least be mentioned in the non-HTML section of the Pages guide and probably deserves a comment in the getStaticPaths reference and Dynamic routes docs.

Particular gotcha to mention:

If the file route is src/pages/[api].json.ts, the api param returned by getStaticPaths need to include .json. Not sure if that’s intended or a bug — we should check with core. Here’s an example:

import type { APIRoute } from 'astro';

export const get: APIRoute = async ({ params }}) => {
  return {
    body: JSON.stringify({
      path: params.api,
    }),
  };
};

export function getStaticPaths() {
  return [
    { params: { api: 'a.json' } }, // ✅ works => outputs '/a.json'
    { params: { api: 'b' } },      // ❌ breaks => outputs '/b'
  ];
}

(I guess under the hood this is essentially working as if the .json part of the filename is not there.)

[delucis]

Quick notes to self:

• remove “endpoint” as keyword in top section of Pages
• better keywords in Non-HTML Pages (particularly endpoint)
• Separate endpoints page with Static & SSR guides
• Example of how to set Content-Type headers on an SSR Response object (Ben to provide)

[delucis]

Quick Q @bholmesdev — you had a good idea for the placement in the nav sidebar of the new Endpoints guide, but I’ve already forgotten sorry 🤦

Was it below Routing?

[bholmesdev]

@delucis I think below Pages would be best! SvelteKit places "pages" and "endpoints" adjacent to one another, and I agree with that placement given how similar they are.

Here's a rough outline of the content I imagined on the Endpoint page as well. You can play with this if you want, but I imagined interweaving SSG and SSR examples without having explicit "SSG" and "SSR" section headers:

• Non-HTML extensions

  • Static assets
  • Dynamic SSR assets

• Dynamic routing

  • getStaticPaths example for static sites
  • the params object -> destructure params in static or SSR modes

• API endpoints

  • the request object
  • returning a Response -> include header setting for a Content-Type

  :point_up: If you agree with this format, I'm happy to draft the API endpoints section myself!