REST API Best Practices: What 1,613 APIs Do

Quick answer: The REST API best practices worth following are HTTPS everywhere, one boring authentication scheme, a documented CORS policy, deliberate versioning, honest status codes, and rate limits you publish in headers. Measured across the 1,613 public APIs listed on publicapis.dev, the most widely ignored of those is CORS: 54% never state a policy at all.

Best-practice guides are written from theory. This one is written from a directory: every claim below is checked against the 1,613 public APIs currently published on publicapis.dev, so you can see the gap between what the guides recommend and what working APIs actually ship. All figures were computed on 14 August 2026.

Should a REST API still be HTTPS-only?

Yes, and this is the one practice the field has genuinely settled. All 1,613 APIs currently listed serve over HTTPS. Not most of them: all of them.

That was not always true. Our archive still contains 43 entries whose documented endpoint was plain HTTP, and every one of them has since been archived or moved. Free certificates removed the last excuse, and an API that answers on port 80 in 2026 reads as unmaintained rather than as a deliberate trade-off.

The practical rule: do not offer HTTP and redirect. Credentials sent to the plaintext endpoint are already leaked by the time your 301 comes back. Refuse the connection instead.

Which authentication method should you choose?

Guides tend to open with OAuth 2.0. The directory tells a different story:

• 813 APIs (50.4%) use a plain API key. Half the field. A header or query parameter, checked against a table.
• 643 (39.9%) require no authentication at all. These are read-only public data, and they are the reason browser demos exist.
• 151 (9.4%) use OAuth. Fewer than one in ten.

So OAuth is the minority choice, and it should be: it earns its complexity only when a third party acts on behalf of a user. If your API returns public or account-scoped data to the account holder, an API key is the correct engineering decision, not a shortcut.

One more finding worth acting on. Six APIs in the set authenticate through a non-standard header of their own invention (five still use X-Mashape-Key, a relic of a marketplace that rebranded years ago; one authenticates on User-Agent). Every one of those forces a special case into every client that talks to them. Use Authorization, or a single clearly named X-API-Key, and nothing else.

Do you need to support CORS?

This is the practice with the widest gap between advice and reality, and the most useful number in this post:

• 600 APIs (37.2%) confirm CORS support.
• 145 (9.0%) explicitly do not support it.
• 868 (53.8%) are recorded as unknown, meaning neither the API's own documentation nor its directory entry commits to an answer.

More than half of all public APIs leave browser developers to discover the answer by triggering a failure. That is not a technical limitation, it is a documentation one, and it costs the API real adoption: a developer evaluating three options will pick the one that did not waste an afternoon.

The subset that gets this right is small and valuable. 236 APIs are both keyless and CORS-enabled, which is the exact combination you can call from front-end JavaScript with no proxy and no secret. Browse the development category for 167 of them, and security for 42 more.

If you are building an API: state your CORS policy in the first screen of your docs, even if the answer is no. Half your competition has not.

How should you version a REST API?

Version from the first public release, before you have users to break. The three approaches that work in practice are a URI prefix, a version header, and a date-based version pinned per account.

A caveat on evidence: we deliberately do not publish a versioning adoption rate from this dataset. The URLs we store are documentation and homepage links rather than API base paths, so counting /v2/ in them would measure how vendors organise their docs sites, not how they version their APIs. It is a good example of a statistic that looks rigorous and means nothing. The mechanics of each strategy, with how Stripe and GitHub actually run theirs, are in our guide to API versioning best practices.

What should your status codes and error bodies say?

Return the code that is true. The common failures are all forms of lying: 200 OK wrapping an error object, 404 for a request that was actually unauthorised, and 500 for anything the handler did not anticipate.

The minimum that a client can act on:

• 400 the request was malformed, and the body says which field.
• 401 you are not authenticated. 403 you are, and still may not.
• 404 the resource does not exist. 429 you are being rate limited.
• 5xx our fault, and a retry is reasonable.

Give errors a stable machine-readable code alongside the human message. Clients branch on the code; the message is for the developer reading logs at 2am, and rewording it should never break anyone.

How should you handle rate limits and pagination?

Publish your limits in response headers, not only in the docs. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset let a well-behaved client slow itself down instead of hammering you until it is blocked. Always send Retry-After on a 429.

This matters more for public APIs than most people assume, because of the auth split above: those 643 keyless APIs are rate limited by IP address, so consumers have no quota to raise and no key to identify themselves with. A shared office network can exhaust the allowance for everyone in the building. If you run a keyless API, publish the limit clearly. If you consume one, treat 429 as a normal operating condition rather than an exception, and back off exponentially.

For pagination, pick cursor-based over offset-based for anything that changes while it is being read, and always return a next link rather than making clients build one.

Frequently asked questions

What are the most important REST API best practices?

HTTPS everywhere, one simple authentication scheme, a documented CORS policy, versioning from the first release, honest status codes, and published rate limits. Of these, HTTPS is universal in practice, while CORS documentation is the one most commonly skipped.

Should I use an API key or OAuth?

Use an API key unless a third-party application needs to act on behalf of a user. Across the 1,613 public APIs we list, 50.4% use a plain API key and only 9.4% use OAuth. OAuth's complexity is worth it for delegated access and rarely for anything else.

Do most public APIs support CORS?

No. Only 37.2% confirm CORS support, 9.0% explicitly do not, and 53.8% do not document it either way. If you are building an API, stating your policy plainly is a cheap way to stand out.

How many public APIs work without an API key?

643 of the 1,613 APIs listed on publicapis.dev (39.9%) require no authentication at all, and 236 of those also support CORS, which makes them callable directly from browser JavaScript. You can filter the directory for keyless APIs.

What status code should a REST API return for an unauthenticated request?

401 Unauthorized when the caller has not proved who they are, and 403 Forbidden when they have but lack permission. Using 404 to hide a resource's existence is defensible for security, but be consistent about it, or clients cannot tell a bug from a permission boundary.