Write Great APIs

We discuss all things APIs: what makes them great, what makes them bad, and what we might like to see in them while Michael plays a lawyer on channel 46, Allen doesn't know his favorite part of the show, and Joe definitely pays attention to the tips of the week.

For those reading this episode's show notes via their podcast player, you can find this episode's show notes at https://www.codingblocks.net/episode157 where you can be a part of the conversation.

Sponsors

• Datadog –  Sign up today for a free 14 day trial and get a free Datadog t-shirt after creating your first dashboard.

Survey Says

How do you prefer to be interviewed?

Take the survey at: https://www.codingblocks.net/episode157.

News

• Big thanks to everyone that left us a new review:
  • iTunes: hhskakeidmd
  • Audible: Colum Ferry

All About APIs

What are APIs?

• API stands for application programming interface and is a formal way for applications to speak to each other.
• An API defines requests that you can make, what you need to provide, and what you get back.
• If you do any googling, you'll see that articles are overwhelmingly focused on Web APIs, particularly REST, but that is far from the only type. Others include:
  • All libraries,
  • All frameworks,
  • System Calls, i.e.: Windows API,
  • Remote API (aka RPC – remote procedure call),
  • Web related standards such as SOAP, REST, HATEOAS, or GraphQL, and
  • Domain Specific Languages (SQL for example)
• The formal definition of APIs, who own them, and what can be done with them is complicated à la Google LLC v. Oracle America, Inc.
• Different types of API have their own set of common problems and best practices
  • Common REST issues:
    • Authentication,
    • Rate limiting,
    • Asynchronous operations,
    • Filtering,
    • Sorting,
    • Pagination,
    • Caching, and
    • Error handling.
  • Game libraries:
    • Heavy emphasis on inheritance and "hidden" systems to cut down on complexity.
  • Libraries for service providers
    • Support multiple languages and paradigms (documentation, versioning, rolling out new features, supporting different languages and frameworks)
• OData provides a set of standards for building and consuming REST API's.

General tips for writing great APIs

• Make them easy to work with.
• Make them difficult to misuse (good documentation goes a long way).
• Be consistent in the use of terms, input/output types, error messages, etc.
• Simplicity: there's one way to do things. Introduce abstractions for common actions.
• Service evolution, i.e. including the version number as part of your API call enforces good versioning habits.
• Documentation, documentation, documentation, with enough detail that's good to ramp up from getting started to in depth detail.
• Platform Independence: try to stay away from specifics of the platforms you expect to deal with.

Why is REST taking over the term API?

• REST is crazy popular in web