- Introduction
- General Usage
- Endpoints
GET/mcje/versionsGET/mcje/versions/:version/block_statesGET/mcje/versions/:version/commandsGET/mcje/versions/:version/registriesGET/mcje/versions/:version/vanilla-assets-tiny/tarballGET/mcje/versions/:version/vanilla-data/tarballGET/vanilla-mcdoc/symbolsGET/vanilla-mcdoc/tarballPOST/hooks/github
Introduction
The Spyglass API provides access to various information that is helpful for data pack/resource pack toolings. It uses misode/mcmeta and SpyglassMC/vanilla-mcdoc under the hood and provides a few advantages over using the GitHub API directly:
-
Accessible within mainland China.
-
Cache invalidation is handled through standard HTTP headers like
ETagandIf-None-Match; no more git commit sha hackery needed on client side. -
Cleaner?
General Usage
The Spyglass API root endpoint is https://api.spyglassmc.com/. Clients must identify themselves using the User-Agent HTTP header; requests without the User-Agent header will be rejected.
Error Handling
All error responses (HTTP status code 4xx and 5xx) will include a JSON body with the following structure:
-
message: (str) A human readable message describing the error details.
Conditional Requests
All API endpoints include an ETag header in the response. Clients should cache the value of ETag along with the response body if possible, which can be achieved using the CacheStorage API on browsers. For future requests at the same endpoint, clients should include the value of ETag in the If-None-Match request header. A 304 Not Modified response will be returned if the resource has not changed since the last response.
Ratelimiting
Each API endpoint has a point cost depending on how expensive it is to serve the request. Each IP address can consume up to 100 points per one hour window before receiving 429 Too Many Requests responses. Additionally, the response time will be degraded starting from 50 requests per 15 minute window.
| Type | Points |
|---|---|
Conditional requests that end up with | 0 |
Non-tarball requests | 1 |
Tarball requests | 5 |
Number of remaining points is provided through the RateLimit-Remaining response header. When 429 Too Many Requests responses are received, the client must wait at least Retry-After seconds before trying again.