Free REST APIs Documentation

Implementation is not launch status

The Countries, States, Cities, Sample Users and Sample Products handlers are implemented. No public deployment or production-security verification has been performed. A local or deployed installation may return 503 until its gateway is configured. No uptime or availability guarantee is implied.

Client API keys are not required. The private reverse-proxy token belongs only on the server; never put it into browser code, copied examples or public requests.

Choose the right dataset

Success responses use success, data and meta. Cities and sample APIs add pagination with page, limit, total and totalPages. Errors use success=false and error.code/error.message. Check the HTTP status before reading data; 200 with an empty array is different from a failure.

Access, limits and retries

All five endpoints accept GET. HEAD omits the body; OPTIONS supports GET/HEAD preflight. Request bodies, unsupported query parameters and duplicate keys are rejected. Search accepts at most 100 characters. Paginated endpoints default to 20 records and cap limit at 100.

The prepared Nginx configuration defaults to 60 requests/minute/IP, burst 20, a global 50 requests/second budget and 10 connections/IP. Operators can change these values. Production enforcement remains unverified. The in-memory development bucket is not a production guarantee.

Honor Retry-After on 429 and avoid automatic retry loops. A 503 can mean disabled access, a missing gateway or service downtime. CORS defaults to wildcard anonymous reads, with no credential support; an operator may restrict origins. Server responses default to a 256 KiB size cap.

Try real requests safely

The playground accepts only the five same-origin routes. It validates parameter syntax, uses a 15-second timeout, rejects redirects and caps the response body at 256 KiB. Static documentation examples are labeled separately from live results.