Caching

Server-side caching

We have a cache for most of our APIs, this means that if what you are asking for has been requested recently it will be provided quicker than if we went to the origin.

For example, if you request information about the server IP mc.hypixel.net, we will check if it has been requested recently, if so we will provide you with the same response.

This also works if you request a favicon for a server we have pinged recently, so we don't need to unnecessarily ping the server again.

For those interested, we generally have 3 cache layers:

  • Internal — This is an in-memory store per node process, the language the API server is written in.
  • Redis — We have a Redis cache in place for regions where multiple backend servers are running.
  • Varnish — We now also have a varnish cache in place, this replaced some cloudflare caching rules we had, which were less effective.

How long do you cache for?

It depends which API you are querying, please see the table below for cache duration.

Our CDN provider, CloudFlare also caches some responses for performance and security reasons.

API Cache Duration
Server Ping 5 minutes
Server Favicon 5 minutes
Is server blacklisted? None, we update the list from Mojang once per hour

Caching responses

We highly suggest you cache API responses locally within your application.

To assist with this we send Cache-Control headers if you are sending ajax requests from a browser.

There are several ways to do this depending on your application.

API Responses

If an API request returns cached data we will add fields to the JSON object, if applicable.

  • took ‐ How long it took to process & respond to your request, in milliseconds.
  • source ‐ Where your response came from, either cache or ping.
  • cache.status ‐ If your response 'hit' our cache or not
  • cache.ttl ‐ How long until the cached response expires (if applicable)
  • cache.insertion_time ‐ When the response was cached originally

We also add HTTP headers to the response which you can interpret in your application.

  • MCAPI-Took ‐ How long it took to process & respond to your request, in milliseconds.
  • MCAPI-Cache ‐ If your request 'hit' our cache or not
  • MCAPI-TTL ‐ How long until the cached response expires (if applicable)
  • X-Varnish-Hits ‐ Potentially the number of hits our varnish cache server has had for this resource
  • X-Varnish-Cache ‐ Potentially if your request 'hit' our varnish cache server or not