An Agent-Friendly HTTP Checklist for Public Data APIs

LLM agents read APIs differently from browsers. They do not click, they fetch, parse, and retry. The difference matters even when the API technically works. Here is the checklist YJTOON applies to its own endpoints.

1. Stable URLs that read like nouns

/api/dataset/awk-reference is better than /api?id=42&t=6f3a. Agents compose URLs from examples; a slug that matches the resource name survives that composition.

2. Content negotiation with a visible default

Support ?format=json, ?format=yaml, ?format=toon, and document the default. An agent that asks for a format it saw in an example should get exactly that format.

3. Machine-readable errors, always

Return structured error bodies ({"error": "..."}) with the right status code. Agents pattern-match on status codes; a 404 that returns 200 with an empty body wastes a whole turn.

4. Rate-limit headers, not just a 429

Expose X-RateLimit-Limit, X-RateLimit-Remaining, and a Retry-After header on 429. An agent that can read remaining quota schedules itself instead of hammering.

5. A static fallback for every dynamic endpoint

If the database is down or the origin is slow, pre-generated files under /static-data/ keep the reference data reachable. Static files are also cache-friendly and CDN-friendly.

6. No authentication by default

For public reference data, authentication is friction with no benefit. If you must rate limit, do it per IP hash and say so in the docs.

None of these require a framework or a new architecture. They are header lines, URL choices, and error shapes.