Net API Notes for 2019/07/25: #GoForTheMoon
On July 20th, I was able to attend the Smithsonian presentation, #GoForTheMoon. It was held on the National Mall and celebrated the 50th anniversary of the Apollo 11 moon landing. There were numerous exhibits at the National Air and Space Museum, booths, and activities. However, the centerpiece was a life-sized projection of the 363-foot Saturn V rocket on the side of the Washington Monument. After counting down, visitors camped out on the grass were treated to a 17-minute show combining "full-motion projection mapping artwork and archival footage to recreate the launch of Apollo 11".
It was an inspirational show. It piqued my curiosity in what the software challenges were to make the historical event possible.
Margaret Hamilton led the software team that powered not just Apollo 11, but all the moon missions, Skylab, and more. It was during this project where she coined the term "software engineering". Margaret also conceived and implemented the concepts failing gracefully and defensive design in an era where they were still shifting bits across registers in a form of Assembly.
Google honored Margaret with a 107,000 mirror mural in the Mojave Desert. Pluralsight has a free course discussing the code of the Apollo 11 Guidance Computer (AGC). Finally, the contents of that code have been lovingly prepared and saved to a Github repository.
We've come a fair way since Margaret's code was managing registers on the moon. Higher-level programming languages abstract developers from having to worry about memory management, allowing them to focus more on business problems. Stable protocols have emerged, enabling developers to create layered architectures. And yet, the pioneering work by Margaret and her team continues to resonate today.
NOTES
EBAY AND AN EXAMPLE ON DEPRECATING APIS
If I've said it once, I've said it a hundred times. I love me a good case study. In this case, eBay shares how they communicate upcoming API changes for its thousands of API users. This includes using the OpenAPI deprecated attribute and an HTTP Protocol status code to convey upcoming changes.
A logical question, for those wonks that keep up with RFCs, is why doesn't eBay use the upcoming Sunset header. Well, Tanya Vlahovic, the author, has a pragmatic discussion of the tradeoffs there, as well.
Everybody talks about creating APIs. However, complete lifecycle management means having a plan to accommodate change. This article is an excellence reference on how to do that.
MODELING DOMAIN CONTEXTS
Finding domain contexts is incredibly tricking. In past issues, I've talked about various techniques for defining otherwise pesky boundaries. Nick Tune also worked through similar issues. He's subsequently shared his experience in a piece called "Modelling Bounded Contexts with the Bounded Context Design Canvas".
You might remember Matt McLarty's Microservice Design Canvas. James Higginbotham has also written a fair amount about his experience adopting the lean canvas to boundary definition. Given the number of people aligning around a common technique, one would have to assume there is something there.
WHITEPAPER: HOW DEVELOPERS USER API DOCUMENTATION (FREE PDF)
I'll admit: I missed this when it first came out. However, given the content, it is worth going back and highlighting the ACM whitepaper, "How Developers Use API Documentation". It attempts to answer the question of what constitutes effective API documentation. Written by Michael Meng, Stephanie Steinhardt, and Andreas Schubert, it also:
- Describes how to structure docs
- Justifies code examples
- Offers additional hints on how to make your API documentation a success
"Our work is driven by the hypothesis that problems with API documentation may in part reflect usability problems, and in particular, that content and structure of the documentation sometimes do not match the expectations and work habits of developers. Consequently, for API documentation to be an effective aid in learning an API, we need to know which general strategies software developers adopt when solving programming tasks, which information they need and which information resources they turn to."
MILESTONES
- 'How to JSON:API' has launched. It features many tutorials in a handful of languages and frameworks to help developers get jump-started.
- The third version of the microservice query language, restQL, was released. It attempts to simplify the job frontend code has calling backend services by creating parallel requests. While I might espouse an experience or BFF pattern for these cases, I could see where this might enable a different approach.
- Lifewingmate has started collecting design guides for Event-based APIs. If you have examples, please consider submitting a pull request.
- Sam Newman, who previously wrote one of the foremost books on microservices, just teased his upcoming book, "Monolith to Microservices: Evolutionary Patterns to Transform Your Monolith".
WRAPPING UP
Interested in meeting with other, like-minded technology folks? Check out WebAPI.events for all your in-person API needs. Also, is there an upcoming activity that isn't mentioned? I'm happy to add to it. Just shoot me an email.
Finally, a much-deserved thank you goes to my Patreon sponsors. They keep me well caffeinated through the mornings and nights required to curate this compendium. Thank you again.
Till next time,
Matthew @libel_vox and matthewreinbold.com