Skip to main content

About GraphQL API

GraphQL API enables you to connect your Upstash database using GraphQL in addition to Redis protocol. The initial version of the API supports Redis Commands. We are planning to have higher level APIs, such as:

  • 2nd level indexing
  • Leaderboard
  • Queue
  • Commenting
  • User/customer management

GraphQL API vs Redis Protocol#

Upstash supports both Redis protocol and GraphQL. Here are some notes that can help you to decide which one to use:

GraphQL API Pros#

  • GraphQL is request (HTTP) based where Redis protocol is connection based. If you are running serverless functions (AWS Lambda etc), you may need to manage the Redis client's connections. GraphQL API does not have such issues.

  • Redis protocol requires Redis clients. On the other hand, GraphQL API is accessible with any HTTP (or GraphQL) client.

  • If you want to access to Upstash database directly from your client side or mobile app, this is only possible with GraphQL API. Redis clients work only on serverside, you need to run your code on a serverless function, container or an instance.

Redis Protocol Pros#

  • Redis protocol have lower latency than GraphQL. In our benchmarks, read latency with Redis protocol is sub millisecond (0.5 msec) while the median with GraphQL API is about 4 milliseconds for GraphQL API.

  • If you have a legacy code based on Redis clients, Redis protocol will help you to use Upstash without a code change.

  • Using Redis protocol, you can benefit from the rich Redis ecosystem. For example, you can directly use your Upstash database as session cache for your express application.

Security and Authentication#

We create 3 type of access keys to access a database via GraphQL API:

  • Read-only: This key can do only queries.
  • Read-write: This key can do queries and mutations.
  • Admin: There are some special commands like keys and flushdb which access or mutates all entries. Only admin key can run those commands.

You need to add a header to your API requests as Authorization: Bearer $YOUR_ACCESS_KEY.

As a good practice, try to use the key with the least priviledge in your application. Especially, exposing your read-write and admin keys in your client side application can be dangerous. Using Serverless functions for the API calls can be a good solution. You can revoke your exposed key in the Upstash console.

We are planning to support a new type of key (custom-key) where you will select the commands which the key will have access.

You can disable GraphQL API completely for a database, if you are not using it.

Cost and Pricing#

Upstash pricing is based on per command/request. In the first version, every GraphQL API call runs a single command on database. So the same pricing listed in our pricing applies to your GraphQL calls too. If we have more complicated APIs which executes multiple commands on database, then we will document them here.

Metrics and Monitoring#

In the current version, we do not expose any metrics specific to API calls in the console. But the metrics of the database backing the API should give a good summary about the performance of your APIs.