REST API Notes for 2017/10/24
MICROSERVICE REALITIES
The first piece that I'd like to highlight this week is Roger Jin's "How to Align Your Team Around Microservices". As he says in the ProgrammableWeb article:
"the poor naming of microservices is one of the reasons behind misconceptions and misapplication of microservices. Lots of developers, even those in 3-man teams, are jumping on the bandwagon of splitting up apps into far too many services without understanding what microservices really are."
I couldn't agree more. In my team's own training, we are continually asked, "how big should my microservice be"? It is a strange situation where everybody is excited to create them, but they have little concept of what microservices are outside of a misplaced notion of size.
Roger wrestled this problem by taking an outcomes based approach. He identified the desired architectural results needed by his teams, while being realistic about the tradeoffs incurred. If you aren't having this conversation in regards to your monolith decomposition, you should.
For a wonderful compendium of microservice pros and cons to be considered, check out Péter Márton's excellent Designing a Microservice Architecture for Failure. While it has been out for a few months, it is an incredibly detailed breakdown of considerations for the microservice conversation is happening within your org.
FIVE THINGS FOR BETTER EXTERNAL APIS
In the same week there were two different "top 5" lists, both dealing with how to make API design better. In the first, Bruno Pedro lists the common frustrations developers have when attempting to use a public API. In the second James Higginbotham, mentions common considerations a company should have before taking an API public. Cross-reference the two pieces and a clearer picture of desired API traits emerges:
- The API must be discoverable
- With clear documentation (something more than just a list of endpoints, perhaps with usage details)
- And an ability to 'kick the tires' that doesn't require a login or credit card details
- That is secure, with rate limiting and endpoint protection
- Measured against KPIs to ensure alignment with business objectives
REVISITING REST'S "ORIGINAL SIN"
I'll conclude with an interesting piece from Phil Sturgeon entitled "Let's Stop Building APIs Around a Network Hack". Phil begins by talking about the concept of "compound document", or when you combine related data into the requested resource to reduce the number of HTTP calls that need to be made. (In other places I've worked, where we weren't using JSON-API, we called this "link expansion".)
Phil argues that a preoccupation on minimizing resource calls in the era of HTTP/2 is wasted effort. Further, he argues that JSON-API's "sparse fieldsets" (where the client can define only the resource fields to be returned) is now null and void.
It is an exciting argument that makes a lot of sense. Are you using HTTP/2 with your REST(ish) APIs? What has been your experience? I'd be interested in learning more.
WRAPPING UP
Check out webapi.events for conferences, meetups, and/or hackathons happening near you. Don't see an event that should be there? Just let me know what is happening with a link - I'd be glad to add it.
Til next time,
Matthew