6 Design Principles for Your HTTP APIs

Consistency

  • It makes it much simpler to interact with your API, since users always know what to expect and don’t have to read the documentation of every endpoint, but can simply go with their gut.
  • It allows writing client libraries that don’t know the exact schema of the API, just the rules you commit to respecting. The Stripe API client is a good example of this: because the structure of requests and responses is always the same, it can build objects dynamically and only needs to be updated when one of the API rules changes.
  • It creates a set of battle-tested guidelines that you can abide by when you are implementing new features in the API. No more discussions around whether to use numeric IDs or UUIDs, because you’ll just go with whatever you already have in place.

Performance

Documentation

Usability

Simplicity

curl https://api.stripe.com/v1/charges \ 
-u your_api_key: \
-d amount=999 \
-d currency=usd \
-d description="Example charge" \
-d source=tok_visa

Evolution

Over to You!

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store