RPC Specification

caution

This is documentation for using Blitz queries and mutations in a non-Blitz app. For example, from a mobile application or some other app.

For using queries and mutations in your app, refer to Using Queries and Using Mutations.

URL

All queries and mutations are exposed at a URL corresponding to it's file path.

File: app/products/queries/getProduct.ts
URL: /api/products/queries/getProduct
File: app/products/mutations/createProduct.ts
URL: /api/products/mutations/createProduct

Request Details

From an HTTP perspective there is no difference between a query and mutation. They are both function calls that get transformed into POST requests.

HEAD

Warms up the lambda. For example, when a component renders on the client that uses a mutation, it will issue a HEAD request to the mutation endpoint immediately on page load so that there's a much higher chance the actual mutation request will hit a warm lambda.

Must always return HTTP

200 OK

HEAD Responses

HTTP/1.1 200 OK

POST

Executes the query or mutation.

Request body must be JSON with the following keys:

params (required) - This will be provided as the first argument to the query or mutation
version (optional) - String containing the version of the built RPC client

Response body is JSON with the following keys:

result - the exact result returned from the query/mutation function or null if there was an error
error - null if success, otherwise an object.

Example POST body:

{
  "params": {
    "where": {
      "id": 1
    }
  }
}

POST Responses

Success

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": {
    "name": "Hello World",
    "description": "This is awesome :)"
  },
  "error": null
}

Bad Request (Not JSON)

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "result": null,
  "error": {
    "message": "Request body is not valid JSON"
  }
}

Bad Request (Missing params)

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "result": null,
  "error": {
    "message": "Request body is missing the 'params' key"
  }
}

Not Found (Wrong method)

HTTP/1.1 404 Not Found

Versioning

Any time you have client-server communication, there is a very real risk of the client & server code becoming out of sync and causing an error. For example, let's say you have a mutation function whose input is a single object. You decide to change the mutation input to be a single array. You make the change and deploy it. Your server code is now updated, but all your users still have the old client code running in the browser. So it's likely you now have client code sending an object to your mutation which is going to error because it's expecting an array.

Now one solution is to only make changes that are backwards compatible, but sometimes you can't do this.

The other solution is to track the version of your client code and your server code. If there is a version mismatch, you can display a friendly message to the user, telling them they need to reload the webpage to continue.

// TOOD: example of an RPC call shielded by a friendly message to the user