HTTP RPC Specification

Methods <-> 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 the pathname
Input parameters are sent as a a query parameter called input which has the shape Record<number, unknown>.
We also need to pass batch=1 as 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`:#

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:#

function MyComponent() {  const post1 = trpc.useQuery(['postById', '1'])  const relatedPosts = trpc.useQuery(['relatedPosts', '1'])
  // [...]}

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:

encodeURIComponent(  JSON.stringify({    0: '1',  // <-- input for `postById`    1: '1',  // <-- input for `relatedPosts`  }))

Batching Example Response#

Example output from server

[  // result for `postById`  {    "id": null,    "result": {      "type": "data",      "data": {        "id": "1",        "title": "Hello tRPC",        "body": "..."        // ...      }    }  },  // result for `relatedPosts`  {    "id": null,    "result": {      "type": "data",      "data": [        /* ... */      ]    }  }]

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

{  "id": null,  "result": {    "type": "data",    "data": {      "id": "1",      "title": "Hello tRPC",      "body": "..."    }  }}

{  id: null;  result: {    type: 'data';    data: TOutput; // output from procedure  };}

Error Response#