[RFC] Change generated API paths to be mobile app friendly

[flybayer]

Problem

Currently the generated API routes are based on the filepath of the query/mutation resolvers.

Example: app/auth/mutations/login.ts -> /api/auth/mutations/login

This means you can't re-organize your file structure without changing the generated API routes. This is very bad for mobile apps because mobile apps always have legacy versions in use. For mobile apps, you want to make zero breaking changes to your API if possible.

Solution

• No longer use filepaths at all for API routes.
• Use a global namespace for queries and mutations, requiring all queries/mutations to have a unique name
• Use /api/rpc/[resolverName] as the generated API route. Examples:
  • app/auth/mutations/login.ts -> /api/rpc/login
  • app/products/queries/getProducts.ts -> /api/rpc/getProducts
  • app/users/mutations/updateUser.ts -> /api/rpc/updateUser

Alternate 1

• Have separate namespaces for queries and mutations
• Use /api/rpc/queries/[resolverName] and /api/rpc/mutations/[resolverName] as the generated API route. Examples:
  • app/auth/mutations/login.ts -> /api/rpc/mutations/login
  • app/products/queries/getProducts.ts -> /api/rpc/queries/getProducts
  • app/users/mutations/updateUser.ts -> /api/rpc/mutations/updateUser

Other Considerations

Versioning

The main other consideration for mobile apps is versioning. What if you want to make a breaking change to a query/mutation? One idea I have is to allow rpc path nesting like this:

app/users/mutations/createUser.ts -> /api/rpc/createUser
app/users/mutations/v2/createUser.ts -> /api/rpc/v2/createUser

That can be implemented a bit later, but we should consider it in this breaking change for api paths.

Backward compatibility for apps depending on current paths

We should be able to use rewrites and concoct a regex that makes the old generated paths re-map to the new paths.

---

So what are your thoughts on this? Anything I'm overlooking? Any clever ideas?

[sergiodxa]

What if, inside the file of each mutation or query, you could export a constant with the path you want? Without the api prefix because it's added automatically. This will let devs customize the URL or change it if they are sure, you could also add a version yourself in case you want to support more than one version.

[flybayer]

Yes, good point. That is something I thought about.

export const config = {
  // Could require /api/ so it's very clear when reading this what the actual path will be
  path: '/api/rpc/myResolver',
}

export default resolverFunction

However, one thing I'm exploring is the possibility to use a app/api/rpc/[...blitz].ts style API route for defining the base of your rpc API. In this case you couldn't overside the full path. You could only overside the path relative to the "rpc root".

[ntgussoni]

I like the exporting the config option. I don't see a reason why you wouldn't be able to customize it completely.

Besides it follows the same logic as all the other exports that next has.

I think that unless you are working with legacy code you don't care about where your endpoints end up, having the chance to override them is useful.

[cherta]

I agree with @ntgussoni here. Having a config that's exported allows devs to fix urls if and when needed, otherwise you don't really care where things end up.

[MrLeebo]

Any reason to not make the api root path configurable? Like if you're making a URL shortener or something you might want to change it in blitz.config.js

- apiRootPath: "/api/rpc"
+ apiRootPath: "/s"

[flybayer]

Is this for all api routes or only the rpc routes?

[MrLeebo]

I'd think all unless that creates a problem

[flybayer]

I think an override for /api/ can be done separately from thes RPC route change. The RPC routes will always use the global api route base.

[aditsachde]

I think this would be a beneficial change. In blitz, there are really three namespaces: API routes, RPC routes, and react pages. Currently, react pages are at / and API routes and RPC routes share /api/. While RPC covers most of the use cases for frontend-backend interaction, I'm making a lot of use of API routes for stuff like webhook processing and things where it'd really make a lot of sense to pull in nest.js or the like. If these were split, it'd be a lot easier to hand off / and /api/rpc to blitz, while routing /api to a nest controller, instead of having to either list all the RPC routes specifically, or it first hit blitz and then get handed off to nest. (A custom server does impact things like automatic static optimization, but there are times where it does make sense.)

[falleng0d]

One of the best features of blitz is the 'Loose Opinions' part. To keep that promise I believe it's best to leave developers to freely build their apis however they want and offer a plug-in-like proxy solution where they can redirect the obsolete routes, giving as many time as needed for the migration to happen.

something like:

// .proxy.js
export const config = {
  redirects: ['/api/createUser', '/api/newCreateUser']
}

you can redirect pages too if you want. all done server side

[flybayer]

We already support this :)

https://blitzjs.com/docs/blitz-config#redirects

[flybayer]

This change is now available in https://github.com/blitz-js/blitz/releases/tag/v0.40.0-canary.0!