A site on API design and tooling, including REST, GraphQL, OpenAPI, and versioning, with a book called Build APIs You Won't Hate.
HN commenters recommend the site and its book as a good introduction to REST API design, and cite its posts on OpenAPI generation.
Not a general solution, but with Hasura, one approach we have seen is to use Postgres views to keep the old graph around as your data model changes.
In general API evolution is tricky and perfect decoupling between API clients and servers not possible (the article talks about this). What one can aim for is a combination of:
1) Adding new query parameters should not break clients
2) Adding new fields to the responses should not break clients
3) Adding new serialization formats (for newer clients) should not break existing clients
#1 & #2 is roughly what you get with GraphQL optional fields.
Phil Sturgeon has good articles on API Versioning[1] and Evolvability[2] for REST API's
[1] https://apisyouwonthate.com/blog/api-versioning-has-no-right-way
[2] https://phil.tech/2018/api-evolution-for-rest-http-apis/
The whole "REST is good and everything else is dumb" is something I've tried to help people get away from for about a decade. These days it's GraphQL is good and everything else is dumb. See some of the comments in here.
> I wish anything built on REST would die. Conflation of the envelope and the payload is idiotic and adds only pain, no value.
Anyway, a reasoned conversation about where REST can be useful even today: https://apisyouwonthate.com/blog/rest-and-hypermedia-in-2019
And a technical comparison for when people need it: https://apisyouwonthate.com/blog/understanding-rpc-rest-and-graphql
And when those technical differences can come in useful or just be annoying: https://apisyouwonthate.com/blog/picking-the-right-api-paradigm
Loooooots of content on all this. :)
https://apisyouwonthate.com and their book(s) offer good advices.
Not a book, but MS REST API Guidelines are pretty good although they don't cover funky important details like how to properly do REST operations/actions.
https://github.com/microsoft/api-guidelines
This is short one based on RedHat VM engineer experience:
https://restful-api-design.readthedocs.io/en/latest/intro.html
Manning has a solid books on topic:
https://www.manning.com/books/the-design-of-web-apis
https://www.manning.com/books/api-design-patterns
Hi, Jean here from Akita. Yes, it's possible to generate an OpenAPI spec, either by running Akita in production or from a HAR file. Here's a blog post someone wrote about using Akita to generate an OpenAPI spec: https://apisyouwonthate.com/blog/creating-openapi-from-http-traffic
for REST APIs, https://apisyouwonthate.com/books/build-apis-you-wont-hate book is my recommendation if you haven't read it already. I read it as a beginner, so it was kind of an eye opener for me on why we should do things a certain way when it comes to API.
I thought https://apisyouwonthate.com/ was pretty good, assuming REST API.