Add GET support for astro:actions

[WesSouza]

Summary

Currently, Astro Actions can be used to send data and perform actions on the server via POST requests.

However, users might want to get data from the server while leveraging browser and server caching, which requires a GET request.

Background & Motivation

I am working on a project and wanted to use astro:actions for its tRPC-like ergonomics. My project contains several framework components which then obtain data from the server utilizing actions.

Those data requests could be cached so concurrent users don't have to reexecute the action, but given all actions are POST, they must reevaluate.

A use case I immediately have is to allow access to collection content on my framework components without sending the entire collection as a prop.

Goals

• Update defineAction to indicate the use of the GET method (such as with a new property method: 'get';
• Add a GET handler on packages/astro/src/actions/runtime/route.ts;
• Allow either object-to-query-string or serialize it using JSON.stringify and send as the input query parameter.

Note

It must be documented that there would be a size limitation on input parameters. However, I do not see it as an impediment given GET API inputs are usually related to filtering and therefore succinct.

Example

export const server = {
  getCollection: defineAction({
    method: 'get',
    input: z.object({ type: z.enum(['blog', 'documents']) }),
    handler: async (input) => {
      const content = await getCollection(input.type);
      return content.map((item) => ({
        id: item.id,
        collection: item.collection,
        data: item.data,
        slug: item.slug,
      }));
    },
  })
}

[bholmesdev]

Oh, this is a nice suggestion! I wonder if we can expand our current accept property to represent this. Perhaps an accept: 'search' alongside accept: 'form' and accept: 'json'? This follows our pattern of using accept to determine how payloads are parsed.

That said, I can see method: 'get' more directly answering the need people have: I want GET so I can cache.

[WesSouza]

I do think it's a different perspective, as you could have both method: 'get' and accept: 'form' if you use a <form> without method, which would generate a GET request.

Basically method, or another keyword, would convey the transport method for the request, and accept the encoding.

To me the four options would be:

Method	Accept	Coding Method
get	form	Identical to the current approach, except obviously for File.
get	json	The query string would serialize the value into the input parameter using JSON.stringify, and then JSON.parse + Zod's parse.
post	form	No change.
post	json	No change.

We could also follow zod-search-params or can-param and be more like PHP which allows any sort of object to be represented as a query parameter.

In these cases:

method: 'get', accept: 'form'

<form action={actions.example.url}>
  <input name="test" value="123">
  <button>Send</button>
</form>

actions.example.url could map to the endpoint so it would be natively usable by a <form> element.

Request:

GET /_actions/example?test=123

export const server = {
  example: defineAction({
    method: 'get',
    accept: 'form',
    input: z.object({ test: z.string() }),
    handler: async (input) => {
      // ...
    },
  })
}

method: 'get', accept: 'json'

Client:

actions.example({ test: '123' })

Request:

GET /_actions/example?input=%7B%22test%22%3A%22123%22%7D

Server:

export const server = {
  example: defineAction({
    method: 'get',
    accept: 'json',
    input: z.object({ test: z.string() }),
    handler: async (input) => {
      // ...
    },
  })
}

[WesSouza]

BTW I looked at the code and see how a getSearchParamsServerHandler could be implemented, and convey the meaning the action would take place in a GET request.

[bholmesdev]

Ah ha, if we want to serialize form and json payloads separately, I could definitely see that working! I was imagining you pass a URLSearchParams() object from the client, but I think an object -> search params serializer would be more intuitive. I'd be on board with this

[lilnasy]

I ended up going with an approach similar to method: get when making astro-typed-api. The de/serializer is pretty simple.

Another option is using a request header, and adding that header name to the response's Vary header list. And, trpc allows caching by json encoding followed by uri encoding the arguments into a search parameter.

[TranscendentalRide]

Want to give my 2-cents here.

Support GET would be a huge win. Specifically because GET supports conditional requests. This where client sends and IF-NONE-MATCH header, a hash received from the server in a prior call. The server still process the request; but only sends a payload if results doesn't match the ETAG value. If there is a match, the server sends a 304 (Not Modified) instead of a 200. Saving bandwidth and time.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/304

Tanstack supports this:

https://tanstack.com/start/latest/docs/framework/react/server-functions

export const getData = createServerFn({
  method: 'GET', // HTTP method to use
  response: 'data', // Response handling mode
}).handler(async () => {
  // Function implementation
})

[Eptagone]

I need this too. Also, it would be great if GET was the default when no input arguments are needed.

[ausminternet]

Any updates on this?

[bholmesdev]

To be transparent: I've stepped away from Astro contributions recently, and I don't think Wes is available / interested in leading the feature. I'll bring this to our maintainers to see if it's roadmap worthy in the near term.

Otherwise, this is a call to anyone following this issue to lead the implementation! I'm happy to assist in PR reviews or questions.