REST API Notes for 2017-09-25
This week I am in San Jose for API World 2017. Downtown San Jose, where the event is held, has ghosts for me. In 2006 I attended the first ever Adobe Community Summit right around the corner from the convention center. It was a multi-day event of user group leaders from across the country who, like myself, wanted to discover how to help our developers become more successful.
This morning I walked past the Adobe headquarters where that first event was held. Things have certainly changed. I can't remember the last time I opened up any software tool Adobe owned, other than an occasional PDF. And the Flash ecosystem is a shadow of its former self. But, here I am, in San Jose, thinking about developer communities. As far as constants in life, there are certainly worse ones. I'll have a recap of my impressions next time.
Now, onto this week's notes!
UPDATED PAYPAL STYLE GUIDE FROM NIKHIL KOLEKAR
The first thing that I wanted to highlight this week was PayPal's updated API Style Guide. Written by Nikhil Kolekar, the post not only explains why the team updated the document after its original publication in 2015. He, more importantly, articulates how the guidelines are only one piece in a larger governance effort. For those looking for a primer on how policy relates to a larger API governance program, start here.
DARREL MILLER ON API VERSIONING AND THE ROLE OF API DESCRIPTION DOCS
What constitutes a breaking change? That may seem like a simple question. However, as Darrel Miller writes on the Azure API Management blog, the question hides a fair amount of nuance. Like I mentioned with Dan Ciruli's piece, versioning can take many forms. Hardcore 'RESTafarians' will maintain that the need for versioning indicates a poorly conceived hypermedia approach to change management. However, the reality is that hypermedia remains a non-obvious, un-straightforward approach to API creation. What articles like Darrel's do is provide the practical insight to get work done.
While also mentioning Darrel, he shared an interesting revelation that he had on the role of API description documentation in organizations. It is easy to look at the HTML-rendered view from an OpenAPI description and assume that API description languages are only about documentation. However, it is important to remember that these formats are as machine-parsable as they are human-readable. This machine-parsable nature is what allows tool chain automation like service discovery registration, gateway provisioning, lifecycle governance, and more. It is exciting to see others realizing that the HTML-rendered view is the least interesting aspect of an API-Design-First approach.
GARY OLLIFFE ON WHEN TO ADOPT MICROSERVICES
I'll end with a piece by Gary Olliffe. On the Australian ComputerWorld site he talks about when companies should adopt microservices. He does a fine job of articulating the challenges microservices were meant to address. He then goes on to make the astute point that many architects that don't face those challenges still adopt the pattern anyway.
I'm always wary of a good rant, but Gary has some great points. Before launching a microservice effort, ensure that the rationale behind it is well-founded. Microservices are an attempt to manage complex software ecosystems. If, rather than managing, microservices are actually the source of complexity, we have a problem. That problem is the most nefarious software anti-pattern: resume-driven development.
WRAPPING UP
I am growing my team! Are you familiar with enterprise software systems, love working with developers, and looking for professional growth? Do you pine for a combination of internal evangelism, product development, and software architecture - something with visibility across the entire enterprise? Have you connected the dots between your microservices and event driven architectures (EDA)? If so, I want to hear from you.
I also spent time this weekend updating webapi.events with the latest, upcoming, meetup.com items. If you know of an API conference, meetup, or hackathon not listed, let me know. As a reminder, I'm speaking at API World 2017 on September 27th. Are you going? If so, I look forward to seeing you there.
Til next time,
Matthew