API Routes Proposal

[blittle]

API Routes

Draft implementation at: Shopify/hydrogen#391

Right now Hydrogen only serves routes that host React Server Components. This proposal adds the ability to host arbitrary data routes.

A route is added by creating a ".server.js" file in the pages directory (just like normal). Instead of exporting a default function that is a component, the file must export an api named function. When called, that function must return a Response object.

export async function api() {
    return new Response("it worked");
}

Note: a route file can only export a default React component or an api named function, not both.

Switch on HTTP Method

The request is passed a Request object. This object can be used to process the response:

const comments = [
  {
    id: 0,
    value: 'some comment',
  },
];

let idCounter = 1;

export async function api(request) {
  switch (request.method) {
    case 'GET':
      return new Response(JSON.stringify(comments), {status: 200});
    case 'POST':
      const newComment = createNewComment(await request.json());
      comments.push(neComment);

      return new Response(JSON.stringify(newComment), {
        status: 200,
      });
    case 'DELETE':
      comments.length = 0;
      return new Response(null, {status: 200});
  }

  return new Response("Comment does not exist", {status: 404});
}

function createNewComment(newComment) {
  return {...newComment, id: idCounter++};
}

Streamed request

export async function api(request) {
  const reader = request.body.getReader();
  
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    console.log('Received', value);
  }
  
  return new Response("complete");
}

Streamed response

export async function api() {
  const response = await fetch(someUrl);
  const { readable, writable } = new TransformStream();
  
  response.body
      .pipeThrough(new CompressionStream('gzip'))
      .pipeTo(writable);
      
  return new Response(readable, { status: 200, headers: { "Content-Encoding" : "gzip" } });
}

Accessing Shopify Data

Because these routes exist outside of react, the useQuery and useShopQuery hooks cannot be directly used. But what if we pass them as params to the api function? These could be special implementations that are usable outside react.

export async function api(request, { useQuery, useShopQuery }) {
    ...
}

Note: this aligns with the proposal in the caching section of Shopify/hydrogen#445

[jplhomer]

I love all of this ❤️

FYI we won't need useQuery as we're already operating in an async context and need no support for Suspense-type functions.

I'm OK with useShopQuery being passed explicitly as a helper 👍

[blittle]

@jplhomer would useQuery still be useful for any of the caching mechanisms?

[jplhomer]

Hmm I hadn't thought of that.

In that case, useQuery (which will soon be renamed to just fetch) could be passed as a param just like you've proposed if the user wants to leverage caching.

If not, they can still use raw fetch in their function 👍

[blittle]

From @vlucas

This proposal says instead of exporting a default function that is the component, but could this also be optionally in addition to as well?

In other words, would this always be either an API OR a component, or could this be both, similar to Next.js getServerSideProps or Remix's loader() method

The reason that a route cannot be both a react server component (RSC) and an API route is that inherently RSC routes are GET requests. The API route handles every request that hits it, including GET. It becomes ambiguous and/or confusing if we allow both in the same file.

[jplhomer]

Revisiting this... I wonder if we could indeed be more permissive here. Since we're building a glob object of components to import, we can theoretically make a decision on whether api will field GET requests based on the presence of a default export:

// GET requests
export default MyFoo() {}

// all other verbs except GET
export async function api() {}

vs:

// ALL verbs, since there is no default export
export async function api() {}

cc @frandiox

[blittle]

Would this still be confusing at all? In that case the api function would get a request object, that request object would just never have a GET method property.

[jplhomer]

I am not confused by that — if I'm not getting method == 'GET' in my api function, I double check to make sure I haven't defined a default export.

[blittle]

I guess my argument is more around someone new, just learning the framework. Would that be a non-obvious thing to figure out?

On a separate note, there is precedence from this in remix, where a route can export a default function (component) and a action function. So maybe not confusing after all?

[frandiox]

Thanks for championing this @blittle !

Everything looks fine to me except for this part:

Note: a route file can only export a default React component or an api named function, not both.

In this case, I find weird that we keep these API functions in src/pages since they are not pages at all.

Should we consider moving them to src/api? Or perhaps allow combining server component and api exports but document clearly that the GET goes to the server component if present?

[byrichardpowell]

I also find API functions existing inside pages wierd and second the suggestion to move them to src/api.

[blittle]

Pros

• It's super explicit and obvious where your API routes are and where your view routes are
• Maybe easier to write tooling that validates or does things differently between the two directories

Cons

• The file structure represents the public URL API for the routes. Would the API routes require a URL prefix? If not, the two separate directories could collide matching the same routes. With a prefix, something like: /api/someRoute Does that make the URL less flexible?
• If you have a specific view that relies on a specific API (coupled), does it make sense for them to live next to each other? In a large app grouping related functionality together makes it easier to grok a codebase.

Unsure

• Routes that host a component and API routes becomes moot.

[blittle]

As noted above, there is precedence for this in remix. Also, where most data fetching is supposed to happen inside the server component, like remix, the component route itself kinda becomes the API.

[jplhomer]

Reminder that the developer completely controls their filesystem and the import glob that generates routes. They could theoretically update the glob to search for files inside a new /api folder.

I think we should colocate everything in pages for now, given that you can export both a default component and an API function from the same route.

maybe someday we rename pages to be routes or somethin

[olavoasantos]

This is great!

I have a comment on Switch on HTTP Method. I feel that having a single method for handling all request methods can lead to messy code that have multiple responsibilities (especially if you're handling multiple methods on a RESTful API).

Considering we're already proposing named exports, what are your thoughts on having different exports for different methods?

Examples:

export async function Get(request) {
  return new Response(await getAllComments());
}

export async function Post(request) {
  return new Response(await createComments(await request.json()));
}

export async function Put(request) {
  return new Response(await updateComment(await request.json()));
}

export async function Patch(request) {
  return new Response(await updateComment(await request.json()));
}

export async function Delete(request) {
  return new Response(await deleteComment(await request.json()));
}

[blittle]

Hi @olavoasantos I love the idea. We went back and forth on the design of the API and decided in the end to keep it simple with a single resolving function. That single function could easily be split into separate functions for each HTTP verb. I think there's more flexibility if we keep it as is.

[frandiox]

What do you think about providing a set of predefined error constructors that can be thrown from API handlers?

export class RestError extends Error {
  constructor(message, status, details) {
    super(message)
    this.name = this.constructor.name
    this.status = status
    this.details = details
  }
}

export class BadRequestError extends RestError {
  constructor(message, details) {
    super(message, 400, details)
  }
}

export class UnauthorizedError extends RestError {
  constructor(message, details) {
    super(message, 401, details)
  }
}

// ...

This could be caught by Hydrogen and converted to responses: throw new BadRequestError('Input is incorrect', { field: 'password', hint: 'Use symbols' }). More examples here.

[blittle]

I love this idea! Maybe I'll put together a more complete proposal of all the response types, and what the standard error response would look like based on each of those types. I think we could add this feature later on, and first get the generic API route functionality shipped.

[mcrstudio]

I'm a fan of this for sure.

[jimmywarting]

how about mimicing the service worker even more like this:

export async function api (evt) {
  const request = evt.request
  evt.respondWith(new Response(...))
}

// or: 
export async function api (request) {
  request.respondWith(new Response(...))
}

[blittle]

That's a good idea. The initial thought for this API was just simplicity, just an async function, Request/Response. A next step from this current API proposal is we'd like to make it even simpler, where you could just return a string, or object, and we'd automatically create the Response object for you:

export async function api() {
  return "Hello world"; // we translate this to new Response('Hello world');
}

// or

export async function api() {
  return { hello: 'world' } // we translate this to new Response(JSON.stringify({ hello: 'world' }), { headers: { "Content-Type": "application/json" }})
}

Though we probably could do similarly with evt.respondWith(). Can you think of any major benefits besides being inline with the Service Worker API? In my experience, not many devs know the service worker API, and are intimidated by it.

[jimmywarting]

I don't know of any other way... just that if it's align more with service worker then the source could more easier be moved into a service worker for offline use so it can function the same way on both server and on the client side.

[jimmywarting]

fyi, i have never tried your tool or ever heard of it before - just saw this thread linked to undini formdata issue

[blittle]

No problem! I really appreciate the feedback! We are relatively new, just publicly released a few months ago.