Update `APIRoute` code snippets and clarify `props` in endpoints

[ArmandPhilippot]

📚 Subject area/topic

Endpoints

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/endpoints/

📋 Description of content that is out-of-date or incorrect

1. Update code snippets using APIRoute

Erika was suggesting on Discord:

export const GET: APIRoute = async ({ params, request }) => {...}
should use satisfies instead

I'm not entirely sure why. I tried both but I don't see any differences... Maybe type inference in some cases?

2. Misleading wording regarding props

In params and Dynamic routing, we say:

but because the endpoint is a function and not a component, props aren’t supported.

In static mode, we can share props through the APIContext object using getStaticPaths. So, I think this is not entirely correct and could be confusing. Here's a small repro using a tweaked version of the code snippet we show above this sentence: https://stackblitz.com/edit/astro-endpoints-dynamic-routing?file=src%2Fpages%2Fapi%2F[id].json.ts,src%2Fpages%2Findex.astro&on=stackblitz

But, yeah, I guess we can't do that with on-demand rendered endpoints. So we might need to precise this only applies to on-demand mode.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

https://stackblitz.com/edit/astro-endpoints-dynamic-routing?file=src%2Fpages%2Fapi%2F[id].json.ts,src%2Fpages%2Findex.astro&on=stackblitz

By clicking on the links, the console should log:

1 Chris
15:22:37 [200] /api/1.json 2ms
15:22:38 [200] / 27ms
2 Yan
15:22:39 [200] /api/2.json 4ms
15:22:39 [200] / 28ms
3 Elian
15:22:40 [200] /api/3.json 5ms
15:22:41 [200] / 18ms

props can be used with endpoints.

[jsparkdev]

Update code snippets using APIRoute

The only difference I see when using satisfies in the following code is how the type of the GET function is displayed.

export const GET = (async ({ params, request }) => {
  const data = { message: "Hello, Astro!" };
  return new Response(JSON.stringify(data), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
      "X-Custom-Header": "MyValue"
    }
  })
})

• When using the type annotation, the type of the function is displayed as APIRoute.
• When using satisfies, the type of the function is shown as

const GET: ({ params, request }: APIContext<Record<string, any>, Record<string, string | undefined>>) => Promise<Response>

Misleading wording regarding props

I think docs is distinguishing between the props of a component and the arguments of a function, but I'm not sure.

If that's not the case, I don't understand it.

[ArmandPhilippot]

The only difference I see when using satisfies in the following code is how the type of the GET function is displayed.

Same. What I meant was that I don't see any TypeScript errors/warnings or obvious advantages of using one or the other.

I think docs is distinguishing between the props of a component and the arguments of a function

This was my first guess as well, but the link on props (the part I quoted) redirects to data passing with getStaticPaths so I still think there is something unclear here.