API Specs, Schemas and Standards

Recently, I tangled with JSON:API and found myself in a love-hate relationship with this specification. While it offers superb rules concerning pagination, relationships, and includes, it also injects complexity into projects that sometimes feel unwarranted.

I'm not advocating dismissing it outright, but my recent frustrations nudged me to ponder specifications beyond JSON Schema and OpenAPI. I questioned the RESTfulness of the API I was crafting—was it genuinely REST or merely RESTish? Why can't JSON be more intuitive, and does the Stripe API serve as a good model to emulate? I turned to our resident expert, Phil, for insights, incorporating past discussions and some stellar community-contributed articles. So, the next time you find yourself overthinking like I did, these articles might steer you towards clarity.

Well, either that or a refreshing stroll outdoors might do the trick 😉

-Alexander

The API Round-Up

Our monthly round-up of articles, news and updates from APIs You Won't Hate and around the web.

JSON API, OpenAPI and JSON Schema Working in Harmony

Phil explores how JSON API, OpenAPI, and JSON Schema can harmoniously work together in API development. JSON API standardizes API design specifics, while OpenAPI and JSON Schema describe the service model and data instances.

Making the Most of JSON:API

Digging further into our archives for this article on JSON:API. Phil covers managing compound documents, filtering relationships, and handling data pagination to sidestep performance hiccups. Through real-world examples, it sheds light on fine-tuning API design to adapt to evolving data needs and client expectations.

Let's Stop Building APIs Around a Network Hack

Wrapping up a trilogy of reflections by Phil on JSON:API, this blog casts a critical eye on the age-old habit of tailoring APIs to network constraints. It questions JSON:API's stress on compound documents to minimize HTTP calls. The piece advocates for a shift towards more precise resources in API design, tapping into HTTP/2's offerings for a streamlined, contemporary approach.

API links vs keys

An article from Google on using links over keys to denote relationships in APIs. It underscores that links pave the way for self-descriptive APIs, facilitating more straightforward navigation and a superior user experience.

RESTful JSON

A simple spec/media type for adding links to JSON APIs and drawing inspiration from how Stripe, Github and others handle links in their REST APIs. I love this spec as it is simple to follow and doesn't create any headaches while at the same time making your APIs more expressive.

Build APIs You Won't Hate

A good fallback, as always, is the book that started my journey into building API's. Although the book is a bit old now, it's still a solid read, and the chapters on pagination and HATEOS provide a reliable guide for how to format your responses.

From Our Community

Articles written and shared in our free Slack community.

API Programs in 2023: From Functional to Transformational

Matthew Reinbold outlines an "API Program Progression Model" with five stages: Functional, Reliable, Intuitive, Strategic, and Transformative. It depicts the evolution from providing basic functionality to revolutionizing companies by creating new revenue streams and redefining value propositions through APIs.

What API hackers need to know about EPSS

I am considering renaming our community section to "Dana's Domain", given Dana's consistency in pumping out content. In this blog, Dana explains how the Exploit Prediction Scoring System (EPSS) helps predict vulnerability exploitation. By integrating EPSS in API hacking, security teams can prioritize remediations effectively, adding a proactive layer to their cybersecurity strategy.

Support APIs You Won't Hate

Thanks so much for reading the newsletter. Our membership program helps support the community by covering production and hosting costs for our articles, podcast episodes, and newsletter.

It would mean the world to us if you'd consider supporting APIs You Won't Hate with a paid membership.

Until next time!