Getting Started

JSON Server turns JSON files into RESTful APIs. Every file becomes a live endpoint at /<username>/<filename> with full CRUD, querying, and nested path traversal.

Base URL

https://json.shahriyar.dev/<username>/<filename>

Replace <username> with the GitHub username of whoever owns the file, and <filename> with the file name.

Quick Example

Given a file products with this content:

GET — Fetch data

const res = await fetch("https://json.shahriyar.dev/johndoe/products")
const data = await res.json()
console.log(data)

Returns full array.

GET — Find by ID

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1")
const data = await res.json()
console.log(data)

Finds item where id or _id matches. Returns the item or 404.

POST — Add item

const res = await fetch("https://json.shahriyar.dev/johndoe/products", {
  method: "POST",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Appends item to array. Returns 201 with created item. ID auto-generated if existing items have id/_id.

POST — Replace item

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "POST",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Replaces entire element at matching ID. Path ID takes precedence over body ID.

PATCH — Update item

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "PATCH",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  body: JSON.stringify({...}),
})
const data = await res.json()
console.log(data)

Merges fields into matching item. Also supports batch update with query params.

DELETE — Remove item

const res = await fetch("https://json.shahriyar.dev/johndoe/products/1", {
  method: "DELETE",
  headers: { Authorization: "Bearer js_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
})
const data = await res.json()
console.log(data)

Removes matching item. Returns deleted item. Also supports bulk delete with query params.

Auth

Public files require no auth for reads. Mutations (POST, PATCH, DELETE) always require API key.

Pass via Authorization: Bearer <key> header or ?api_key=<key> query param.

See Authentication.

Response Format

GET returns raw data. Mutations wrap response:

Errors:

Rate Limits

• Per-file: 60 requests/min sliding window — 429 with Retry-After
• Per-account: 100,000 requests/month — resets 1st of each month

Admin accounts bypass limits.

CORS

All endpoints return Access-Control-Allow-Origin: *. Works cross-origin.