REST API Notes for 2018-04-19
Things are starting to thaw in the DC area just in time for me to fly to the icy Dakotas. Here are the pieces that, I hope, will help keep my brainpan warm over the coming weekend.
"Z" ON API MATURITY
Not all API designs are the same. Some designs are more "mature" than others. But what does that mean?
Zdenek Nemec does an excellent job summarizing and contrasting two of the more well-known classifications of APIs. The Richardson Maturity Model, for example, segments APIs by how they employ hypermedia controls. The Amundsen Maturity Model, relatedly, classifies a design according to its degree of abstraction (database, object, resource, affordance, etc.). The various levels in both models are illustrated with sample request/responses.
Understanding the tradeoffs that come at each level is important. In his piece, "Beyond REST", Jose Montoya powerfully breaks down the basic tradeoffs in RESTful API design:
- Client-server style adds simplicity, scalability, and evolvability
- Stateless style adds scalability but reduces network performance
- Caching style adds simplicity and scalability
- Uniform interface style adds evolvability but reduces network performance
- Layered system style adds scalability and evolvability
Keeping these tradeoffs in mind, along with identifying the appropriate maturity level for your design, means you'll create an API at the correct level.
COMMUNICATING API CHANGES
As much as I encourage upfront thought put toward minimizing change, I acknowledge that it happens. When it does, it is imperative that those changes are communicated out. Over at the Nordic APIs blog, Kristopher Sandoval describes a number of effective methods. While the article is written from the perspective of an external facing API, all of these channels are relevant for internal APIs, as well. Just replace the social media channels of Twitter and Facebook with your internal CMS and Slack support channels.
"THE WORLD THROUGH AN API"
I spend a fair amount of time auditing developer-centric presentations. In "The World Through an API", the business case for APIs is made. The arguments aren't new, especially to REST API Notes readers. However, I appreciated hearing old arguments reframed in a different light.
In the last notes, I mentioned the commonality among successful, external API programs:
- Software-as-a-service (SaaS), where the software is already built. Think the original incarnation of Salesforce, where it was an entire customer relationship management (or CRM) system that could be integrated with. You integrate with a SaaS.
- Platform-as-a-service (PaaS), where all of the pieces to build software are readily accessible but the integrator brings their own logic. Twilio or Sendgrid, in my mental model, are here. You program for* a PaaS.
- Infrastructure-as-a-service (IaaS), where virtual servers and related raw-compute services are sold. AWS, Azure, etc are here. You deploy to an IaaS.
Keep these possible outcomes in mind when evaluating the business strategy discussed in the video.
MILESTONES
- In the past few weeks, an authentication bypass vulnerability found in auth0 identity platform. To the team's credit, they fixed the problem, on their end in less than 4 hours. However, it took almost six months for clients to migrate off problematic SDK integrations. Bottom line: SDKs are great to get people started, but they also mean the speed with which a problem is corrected is the rate of the slowest client development pipeline.
- "Event-Driven Microservices, A Beginner's Guide" is an e-book, written by Fran Mendez, released this week. It covers the basics of event-driven microservices and message brokers like Apache Kafka and RabbitMQ.
- The Red Hat Developer program has also release an ebook, "Introducing Istio Service Mesh for Microservices". Although focused on a specific platform, it is a gentle introduction to the concept of service meshes. It is authored by Christian Posta and Burr Sutter.
WRAPPING UP
If you're looking for an upcoming API conference to attend I'd encourage you to check out webapi.events. It list in-person conferences and meetups around the world. And if you know of an event that isn't list shoot me a quick note - either respond to this note directly or send me an email at 'hello@matthewreinbold.com'.
Til next time,
Matthew