REST API Notes for 2017/10/31 - Back to the Beginning
Today is Halloween. While your minions may be busy preparing for all sorts of ghoulish tricks for later this evening, I come bearing treats of a different sort.
GETTING STARTED WITH RESTFUL API DESIGN
Several months(!) ago, REST API Notes reader Eduar responded with a very simple question:
"I want to learn about APIs. Where do I start? What resources do you recommend?"
I've been thinking about that question ever since. Thinking back on my own career, I'm reminded of the years of trial and error that contributed to my own perspective. Telling someone to "fail a lot at companies of all sizes" isn't very helpful. There are courses from online education outlets like CodeCademy and Udacity but I haven't audited them. Also, at a quick glance, many of the offerings seemed tied to a specific language or framework.
Likewise, I also am increasingly skeptical of throwing out book recommendations. There are some fantastic resources available if you have the time and tenacity to immerse yourself in deep study. If you already practice API design, adding an additional perspective is not that big of deal. But taking the enthusiasm of someone new and smothering it under a handful of titles for a "complete" perspective isn't right either (and, unfortunately, I do not believe there is a single book that encompasses everything; it is much more like a progression).
Finally, the last thing I'd do is tell somebody new to go read Fielding's dissertation. There's good stuff there, sure. However, that is kind of like telling someone hungry that they need to learn supply chain economics before they get a sandwich. Fielding is abstracting software architectural styles for the ages; most of us are just trying to successfully complete a sprint.
What is someone new to APIs and wants to create good designs to do?
INTRO TO APIS WITH GOOGLE SPREADSHEETS
One barrier to any learning situation is getting software configured. That is why I love Martin Hawksey's approach of using Google Spreadsheets for introducing APIs. Spreadsheets don't have the same level of intimidation, even for less technical learners, than a required list of installed dependencies. Spreadsheets, particularly cloud-based ones, get people up and running quickly.
Martin's exercises walks a reader through the consumption of Flickr's API, covering basics like retrieval of information, payload parsing, and solving a problem with someone else's data. It doesn't go deep, but it is a fantastic, low-barrier-to-entry way of introducing what APIs are about to a new audience.
LANGUAGE/FRAMEWORK AGNOSTIC THEORY
Going a step further, we need something nuanced like a book but as approachable as a webpage. For that, I'd recommend Todd Fredrich's REST API Tutorial. Delivered in a series of short, approachable pages, Todd begins with the six constraints that comprise a RESTful API. He discusses why each is important and how, together, the deliver functionality in a way the scales like the web.
Todd then goes on to include a number of practical conventions to consider in your own designs. For example, the page on what makes intuitive names (and the subsequent anti-patterns) is a great read.
TYING IT ALL TOGETHER
With those two approachable, introductory pieces I hope that Eduar, and the many like him, are off on the right foot as they begin their API journey. But that is my opinion. What have you found to be helpful? What resources have you found yourself returning to on a regular basis?
Let me know. I'd love to share some of your answers in a future newsletter.
MILESTONES
Numerous folks are either already at, or traveling to, the 2017 API Strategy and Practice Conference in Portland, OR. For those looking to follow along, '#apistrat' appears to be the hashtag to camp. I'm looking forward to breaking down and sharing the best the conference has to offer next week.
Also of note is a slew of API and SDK related updates from the Microsoft Outlook team. This includes deprecation of the Outlook REST API v1.0. Like many, the change is due to a move from 1.0's basic authorization to 2.0's Oauth 2.0 authentication model. I mention it not so much because I think I have a number of readers who consume this, specific, API. Rather, the timelines and communication presented are a great example of how to do deprecation right.
WRAPPING UP
I've now added the first 2018 conference to webapi.events. (Yikes, where has the year gone?) Check out that site for conferences, meetups, and/or hackathons happening near you. If you don't see an event that should be there let me know; either respond to this directly or send me an email at 'hello@matthewreinbold.com'.
Speaking of 2018, are you looking for a new challenge? Interested in leading large change at a company with real impact? Does my recent governance post strike a chord? If so, I'm hiring for an exciting opportunity on my team. Have questions? Let's talk.
Til next time,
Matthew