rembMethods <-> Type mapping
HTTP Method
Mapping
Notes
GET
.query()
Input JSON-stringified in query param.
e.g. myQuery?input=${encodeURIComponent(JSON.stringify(input))
POST
.mutation()
Input as POST body.
n/a
.subscription()
Subscriptions are not supported in HTTP transport
Batching
When batching, we combine all parallel procedure calls of the same type in one request using a data loader.
- The called procedures' names are combined by a comma (
,) in thepathname - Input parameters are sent as a query parameter called
inputwhich has the shapeRecord<number, unknown>. - We also need to pass
batch=1as a query parameter. - If the response has different statuses we send back
207 Multi-Status_(e.g. if one call errored and one succeeded) _
Batching Example Request
Given a router like this exposed at /api/trpc:
server/router.ts
tsx
export const appRouter = trpc
.router<Context>()
.query('postById', {
`input: String,`
`async resolve({ input, ctx }) {`
`const post = await ctx.post.findUnique({`
`where: { id: input },`
`});`
`return post;`
`},`
})
.query('relatedPosts', {
`input: String,`
`async resolve({ ctx, input }) {`
`const posts = await ctx.findRelatedPostsById(input);`
`return posts;`
`},`
});
.. And two queries defined like this in a React component:
MyComponent.tsx
tsx
export function MyComponent() {
const post1 = trpc.useQuery(['postById', '1']);
const relatedPosts = trpc.useQuery(['relatedPosts', '1']);
return (
`<pre>`
`{JSON.stringify(`
`{`
`post1: post1.data ?? null,`
`relatedPosts: relatedPosts.data ?? null,`
`},`
`null,`
`4,`
`)}`
`</pre>`
);
}
The above would result in exactly 1 HTTP call with this data:
Location property
Value
pathname
/api/trpc/postById,relatedPosts
search
?batch=1&input=%7B%220%22%3A%221%22%2C%221%22%3A%221%22%7D *
*) input in the above is the result of:
ts
encodeURIComponent(
JSON.stringify({
`` 0: '1', // <-- input for `postById` ``
`` 1: '1', // <-- input for `relatedPosts` ``
}),
);
Batching Example Response
Example output from server
HTTP Response Specification
In order to have a specification that works regardless of the transport layer we try to conform to JSON-RPC 2.0 where possible.
Successful Response
Example JSON Response
ts
{
id: null;
result: {
`type: 'data';`
`data: TOutput; // output from procedure`
}
}
Error Response
Example JSON Response
- When possible, we propagate HTTP status codes from the error thrown.
- If the response has different statuses we send back
207 Multi-Status_(e.g. if one call errored and one succeeded) _ - For more on errors and how customize them see Error Formatting.
Error Codes <-> HTTP Status
ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
NOT_FOUND: 404,
INTERNAL_SERVER_ERROR: 500,
UNAUTHORIZED: 401,
FORBIDDEN: 403,
TIMEOUT: 408,
CONFLICT: 409,
CLIENT_CLOSED_REQUEST: 499,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
METHOD_NOT_SUPPORTED: 405,
Error Codes <-> JSON-RPC 2.0 Error Codes
Available codes & JSON-RPC code
Dig deeper
You can read more details by drilling into the TypeScript definitions in