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

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 development and it's really tough to do anything without it.
• It's simple. Well, not really if you consider the 43 things you need to think about.
• Some things about REST are great by design, such as:
  • By using it, you only have one protocol to support,
  • It's verb oriented (commonly used verbs include GET, POST, PUT, PATCH, and DELETE), and
  • It's based on open standards.
• Some things about REST are great by convention, such as:
  • Noun orientation like resources and identifiers,
  • Human readable I/O,
  • Stateless requests, and
  • HATEOAS provides a methodology to decouple the client and the server.

Maybe we can steal some ideas from REST

• Organize the API around resources, like /orders + verbs instead of /create-order.
  • Note that nouns can be complex, an order can be complex … products, addresses, history, etc.
  • Collections are their own resources (i.e. /orders could return more than 1).
• Consistent naming conventions makes for easy discovery.
• Microsoft recommends plural nouns in most cases, but their skewing heavily towards REST, because REST already has a mechanism for behaviors with their verbs. For example /orders and /orders/123.
  • You can drill in further and further when you orient towards nouns like /orders/123/status.
• The general guidance is to return resource identifiers rather than whole objects for complex nouns. In the order example, it's better to return a customer ID associated with the whole order.
• Avoid introducing dependencies between the API and the underlying data sources or storage, the interface is meant to abstract those details!
• Verb orientation is okay in some, very action based instances, such as a calculator API.

Resources We Like

• API (Wikipedia)
• The Linux Kernel API (kernel.org)
• gRPC (Wikipedia)
• S3 Compatible API (Backblaze)
• Storing Data Shouldn't Cost More Than Generating It (Wasabi)
• Top 50 Most Popular APIs on RapidAPI (2021) (rapidapi.com)
• Free Public APIs for Developers APIs (rapidapi.com)
• API Reference (Datadog)
• OData – the best way to REST (odata.org)
• Understand OData in 6 steps (odata.org)
• Best practices for REST API design (Stack Overflow)
• Best Practices in API Design (swagger.io)
• Web API design (docs.microsoft.com)
• The Web API Checklist — 43 Things To Think About When Designing, Testing, and Releasing your API (mathieu.fenniak.net)
• Google API Design Guide (apistylebook.com)
• The DevOps Handbook – Create Organizational Learning (episode 145)
• How to Scrum (episode 156)
• State of JS 2020 (stateofjs.com)

Tip of the Week

• Docker Desktop: WSL 2 Best practices (Docker)
  • Experiencing déjà vu? That's because we talked about this during episode 156.
• With Minikube, you can easily configure the amount of CPU and RAM each time you start it.
  • Minikube default CPU/Memory (Stack Overflow)
• Listen to American Scandal. A great podcast with amazing production quality. (Wondery)
• If you have a license for DataGrip and use other JetBrains IDEs, once you add a data source, the IDE will recognize strings that are SQL in your code, be they Java, JS, Python, etc., and give syntax highlighting and autocomplete.
  • Also, you can set the connection to a DB in DataGrip as read only under the options. This will give you a warning message if you try a write operation even if your credentials have write permissions.
• API Blueprint. A powerful high-level API description language for web APIs. (apiblueprint.org)
• Apache Superset – A modern data exploration and visualization platform. (Apache)
• Use console.log() like a pro. (markodenic.com)
  • Turns out we did discuss something similar to this back in episode 44.
• Telerik Fiddler – A must have web debugging tool for your web APIs. (Telerik)
• New Docker Build secret information (docs.docker.com)