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
Accessing nested procedures
Nested procedures are separated by dots, so for a request to byId below would end up being a request to /api/trpc/post.byId.
ts
export const appRouter = router({
post: router({
`byId: publicProcedure.input(String).query(async (opts) => {`
`// [...]`
`}),`
}),
});
Batching
When batching, we combine all parallel procedure calls of the same HTTP method 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 = t.router({
postById: t.procedure.input(String).query(async (opts) => {
`const post = await opts.ctx.post.findUnique({`
`where: { id: opts.input },`
`});`
`return post;`
}),
relatedPosts: t.procedure.input(String).query(async (opts) => {
`const posts = await opts.ctx.findRelatedPostsById(opts.input);`
`return posts;`
}),
});
... And two queries defined like this in a React component:
MyComponent.tsx
tsx
export function MyComponent() {
const post1 = trpc.postById.useQuery('1');
const relatedPosts = trpc.relatedPosts.useQuery('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
{
result: {
`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 to customize them see Error Formatting.
Error Codes <-> HTTP Status
ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
UNAUTHORIZED: 401,
NOT_FOUND: 404,
FORBIDDEN: 403,
METHOD_NOT_SUPPORTED: 405,
TIMEOUT: 408,
CONFLICT: 409,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
UNPROCESSABLE_CONTENT: 422,
TOO_MANY_REQUESTS: 429,
CLIENT_CLOSED_REQUEST: 499,
INTERNAL_SERVER_ERROR: 500,
NOT_IMPLEMENTED: 501,
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