Developer Accessible APIs

APIs That Get Out of the Developer's Way

Most API providers start new users off with extensive documentation, tutorials, and examples. Those resources are valuable, but they carry real costs. Behavior must be documented exhaustively because developers have no easy way to test corner cases themselves, docs inevitably fall out of sync with the implementation, and examples assume a particular language or toolset that may not match what the reader uses.

The alternative is to make the API itself accessible: design it so developers can probe it directly with whatever tools they already have, before they commit to building a client around it. This isn't just a short-term convenience. In a world where both clients and servers change over time, breakages are inevitable. When they happen, you want a developer to be able to jump in with a generic HTTP client and diagnose the problem quickly, without wading through SDK-specific setup or specialized libraries.

Developer accessibility isn't a single feature; it's a collection of design patterns that lower the barrier between a developer and a live API.

Adopt OAuth 2

Much of the complexity in OAuth 1 comes from an extra cryptographic layer bolted on top of the protocol. OAuth 2 relies on HTTPS instead and is significantly more usable as a result. OAuth 1 APIs frequently require specialized consumer libraries because the signing dance is too tedious to do by hand. OAuth 2 APIs, by contrast, can be called from any generic client—including plain Curl. Even Twitter, known for its historically restrictive APIs, provides a straightforward way to procure an OAuth 2 access token.

Accept bearer tokens

A simple companion pattern to OAuth 2 is to let clients authorize with a bearer token passed via the Authorization header. This keeps the entry point trivial: any client that can send an HTTP header can authenticate, with no base64-encoding or manual request signing required.

curl -H "Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef" ...

Keep it Curlable

A recurring theme across these patterns is that an API should work fine from any generic HTTP client, with Curl serving as the baseline. This helps new developers immediately experiment with the API, and it helps API owners during development of new endpoints, too. A small but effective improvement is to detect Curl clients and pretty-print JSON responses for them, making an exploratory call far more pleasant to read.

Return scope hints in responses

Letting developers discover an endpoint's requirements while testing beats expecting them to dig through reference documentation. OAuth-enabled apps often request broader scopes than they exercise, which is poor security hygiene. Returning a header like OAuth-Scope-Accepted on responses gives a developer an immediate, visible cue as to what permissions an endpoint actually needs to operate, so they can tighten their app's scope before shipping.

Oauth-Scope: global
Oauth-Scope-Accepted: global identity

Return ordering hints in responses

Some APIs let list ordering be controlled through a request header. In Heroku's V3 platform API, ordering is specified through a Range header, but ordering is only supported on certain fields. However useful, the developer shouldn't be forced to look up valid ordering fields in the reference docs. The API announces what's possible by echoing an Accept-Ranges header in list responses, so one simple exploratory call shows exactly which ranges or fields are supported.

Accept-Ranges: id, name
Range: id ..

Ship a service stub

Another way to encourage safe exploration is to distribute a stub of your service. A stub allows a developer to make API calls that, if executed against production, would mutate data or have other real side effects. Heroku publishes such a stub for the platform API, letting developers try risky calls in a contained environment before interacting with the real system.

Publish a programmatic map

An idea gaining traction in the Hypermedia world is to return a set of links at the API's root endpoint, pointing to all other available endpoints. When paired with strong RESTful conventions, a developer can find their way around the API by simply following these links with Curl, potentially bypassing the docs entirely. A real-world example is GitHub's API root, which enumerates the available top-level resources and lets a developer discover the surface of the API by navigating from there.

curl https://api.github.com

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/legacy/issues/search/{owner}/{repo}/{state}/{keyword}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "notifications_url": "https://api.github.com/notifications",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos/{?type,page,per_page,sort}",
  "organization_url": "https://api.github.com/orgs/{org}",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/legacy/repos/search/{keyword}{?language,start_page}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "team_url": "https://api.github.com/teams",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/legacy/user/search/{keyword}"
}