RFC: Easier calling of tRPC queries with Postman etc

Summary

This is a two-part thing:

1. Prefix “tRPC query params” with a _
2. Enable users to easier query the endpoints with Postman, etc.

Describe the solution you’d like to see

Part 1 - Prefix queries

Prefix queries

• We should likely prefix batch, input, etc with a _ (or maybe _trpc_)
• We should also make the use of a transformer being stated in the query params, like _transform=1 so we can know on the backend if something was called with - already on the roadmap

Part 2 - allow querying without JSON.stringifying query input

Given a postById procedure with this input:

z.object({
  id: z.string(),
})

It would be nice to be able to call the endpoint in both these ways:

• /api/trpc/postById?_input=%7B%22id%22%3A%221%22%7D (encodeURIComponent(JSON.stringify({ id: "1" }))})
• /api/trpc/postById?id=1

Caveats / drawbacks

• How to deal with id was a z.number()?
  • Enforce coercion with a .transform?
• How do we deal with input not being a z.object()?
• Maybe a rule could be added on the t’s RootConfig to enforce it to be an object
• Maybe this should be dynamically opt-in or out so one could only allow it in i.e. development
• How to deal with more complex inputs? I.e. z.object({ arr: z.array(z.string()) })

Desribe alternate solutions

• Not doing it or encouraging people to use trpc-openapi
• #1939 helps here too by allowing users to call query endpoints with a POST

Additional information

Alternative new solutions to tRPC (that have way fewer other features) use this as a selling point w/o recognizing that we have a good reason of doing it this way.

👨‍👧‍👦 Contributing

• 🙋‍♂️ Yes, I’d be down to file a PR implementing this feature!

[felix-wooliesx]

My solution to this problem was to use a Pre-req script in postman to convert a standard JSON body into the encoded and stringified input query string param using the following snippet:

// move the request body into an `input` query param in the format trpc expects

// body.raw is already stringified json
const input = encodeURIComponent(pm.request.body.raw);
pm.request.addQueryParams(`input=${input}`);
// remove the request body
pm.request.update({
    body: undefined
})

This allows me to easily edit the data that’s sent as part of a query as it’s simply just editing JSON in the Body page in postman.

Perhaps a docs page outlining something like the above is all that’s needed in this case?

[felix-wooliesx]

Hey @felix-wooliesx, this looks awesome, do you wanna add something to the docs?

Yeah sure I can look into that at some point soon 🙂