Net API Notes for 2019/10/03
One whirlwind, mid-week trip to New York City, and it is time, again, to post another Net API Notes.
NOTES
GRAPHQL AT COURSERA
GraphQL has been in the public conversation long enough that we're now seeing interesting, multi-year observations of what worked and what didn't. Jon Wong is the latest and talks about his experience using GraphQL while at Coursera in "Evolving the Graph".
In a REST-ish or net API, the decision to go code-first or design-first isn't apparent. Both ways come with pros and cons. With GraphQL, there are similar tradeoffs. Coursera initially chose to go code-first rather than design a Schema Definition Language document (or SDL). Fast forward a few years, and:
From a technical standpoint, it was really simple to get new things into the GraphQL schema, but we never really had a strong opinion about whether these new things should be in the schema in the first place. Again, given the context of the project, this explicitly wasn’t a goal, but after three years of unbounded growth, our GraphQL schema was bursting at the seams: We have more than 7,000 types, and more than 650 root types. One of the benefits of GraphQL is discoverability, but with so many entities, it was really difficult to figure out which APIs existed already, and without proper governance of the schema, these APIs were not particularly well documented, either.
There's more great nuance throughout the rest of the piece. However, I found the switch to a schema-design-first over data-first approach, even when dealing with a GraphQL API, enlightening.
OVERVIEW OF EVENT STREAMING MICROSERVICES
This article, by Gwen Shapria, came out earlier this year. However, "Schemas, Contracts, and Compatibility" is one of the best high-level overviews of event-streaming microservices that I have seen.
There are lots of ways for services to talk with each other. Many of us default to using HTTP, as that is what we're most familiar with, have the infrastructure to support, etc. However, assuming that inter-service communication must be HTTP driven bypasses a beneficial, real-time architectural solution. Check it out.
UP AND COMING HTTP/3 SUPPORT
Speaking of HTTP, we should talk about the latest, greatest making its way onto the web as I type. I know that HTTP/2 support is not yet ubiquitous within many API environments. This is even though it offers potential speed increases.
But good news! If you have yet to take advantage of HTTP/2, you can skip a generation and go directly to HTTP/3!
I'm joking (mostly). However, folks should, at a minimum, have a high-level understanding of what the new protocol offers. For a quick primer, I'd recommend Jesus M Gonzalez-Barahona's recent tweet stream. If you are interested in more after that tidbit, check out Daniel Stenberg's more in-depth presentation on YouTube. Then ask your middleware vendor for an ETA.
MILESTONES
- ReadMe raised $9 million to help customers customize their API documentation. What is kind of neat here is that it isn't just some nicer CSS over rendered OpenAPI descriptions. The software creators use actual API logs to create what they call "dynamic documentation".
- Kong has acquired Insomnia, an open-source REST client.
- GraphQL Editor v2.0 has been released. If somebody can answer how a "Levenshtein algorithm" helps create mock services, I'd appreciate it.
- The UK Government has recommended OpenAPI v3 to describe all RESTful APIs. In their statement, they cite the many available tools as a sign of specification maturity and adoption.
- Looking for an OpenAPI-to-UML-and-back solution? Check out WAPIml. Given my glut of recent AI reading, it took me an embarrassing amount of time to realize that the 'ml' stood for 'modeling language', not 'machine learning'.
- If you're a Java Spring developer, Spring HATEOAS 1.0.0 has been released.
WRAPPING UP
Want more API conversation while you're out and about? Check out NetAPI.events. There's still plenty more upcoming opportunities to get together with your local community.
Further, if you know of a meetup, hackathon, or conference that is missing, let me know. I'd be happy to add it.
Also, a big thank you goes out to my Patreons. I've been thinking about doing a "This Old House" write-up for those folks, except for APIs; identify a useful, but problematic, net API (Wikipedia, I'm looking at you), identify the trouble spots, and then build up a theoretical design that is more intuitive, accommodating, and fitter than the original. Would anybody find this kind of real-world design exercise useful? If so, let me know.
Till next time,
Matthew @libel_vox and matthewreinbold.com