REST API Notes for 2018-03-13
In March, numerous API luminaries have, seemingly, sprung to life. Publishing weekly is infrequent enough to aggregate similar thought while being frequent enough to track emerging thought leadership. Different authors, when they agree, reinforce valuable messages. If they disagree, the contrasting points help the truth stand out in sharp relief. This week's collections are all about API Documentation and microservices.
API DESIGN-FIRST/DOCUMENTATION
Not all API Documentation is the same. Last week Keith Casey shared a gangbusters piece articulating not one, not two, but three different types of API documentation. As I mention in my recently published guidance for API product managers, different audiences will need different things from an API. This, also, extends to the API documentation.
Phil Sturgeon spent some time documenting the maturation of his Design-First workflow. It is a fantastic blueprint teams can follow. Kin Lane was impressed.
Much of that API Design-First workflow wouldn't be possible without the OpenAPI specification. For an example of how eBay uses API descriptions in their business, Shekhar Banerjee has shared an overview.
Finishing up the documentation section, Faria Rehman has written about the most common mistakes that developers make in their OpenAPI 3 files. Faria works as a support engineer for APIMatic. As such, this is valuable aggregated analysis from a tool vendor that has supported the format since it was a release candidate.
API ACADEMY MICROSERVICE PRESENTATIONS AND TRAINING
I regularly feature the work from CA's API Academy, and for good reason. The community is lucky to have a group dedicated to not only advancing the API craft, but regularly sharing as much of their work as they do. They have been on the road this spring, and that means their thoughtful work has been popping up online.
- Erik Wilde shared his presentation, "Changing APIs at Microservices Scale"
- Mike Amundsen has his entire SACON training, "Learning RESTful Microservices from the Ground Up" available (including exercises, notes, and slides)
- Mike also posits about the future of open APIs on the Web in the presentation "Cathedrals in the Clouds"
- Last but not least, Matt McLarty posted his slides on "API Security in a Microservice Architecture
MILESTONES
Irakli Nadareishvili announced the IANA has accepted his registration for a new Mime type, 'Hyper'. As Michael Hibay rejoiced, "[hyper] opens up the options for any user agent to negotiate any format they choose". I'd love to hear what people's experiences are like giving the new mime type a go.
Phil Sturgeon announced that Speccy, his project, is now not only an OpenAPI linter, but also checks for quality rules. If you are building an OpenAPI workflow for API management, this is certainly a tool worth considering.
Finally, Hootsuite announced the availability of a tool for microservice observability. More than a "microservice deathstar", it gives those managing these deployments a reasonable shot at awareness with microservice's heightened levels of complexity.
WRAPPING UP
I recently updated webapi.events with the latest crop of events. If you have an event that isn't listed either respond to this note directly or send me an email at 'hello@matthewreinbold.com'. Not a problem to help people connect.
Til next time,
Matthew