GraphQL, gRPC and REST, Oh My! A Method for Unified API Design • Mike Amundsen • GOTO 2020

This presentation was recorded at GOTO Chicago 2020. #GOTOcon #GOTOchgo

Mike Amundsen - The (API) uncle you wish you had — the ultimate expert

ABSTRACT
As APIs are adopted in more and more organizations, the need for successful API design and implementation becomes more pressing. Companies that adopt a single API definition format (OpenAPI, AsyncAPI, Schema Definition Language, Protobuff, etc.) are likely to find their options limited as their API ecosystem grows and matures over time.
In order to avoid forcing the entire company to adopt a single API style or format, no matter the requirements of providers and consumers, we need a unified API design process. One that doesn't pre-determine implementation details such as REST, GraphQL, gRPC, and others. Based on materials in Amundsen's book "Design and Build Great Web APIs", this talk describes a simple, repeatable process for API designers to capture and document design details in a way that allows API developers to make their own decisions on which API style best fits the needs of the company and the consumer.
Whether you are responsible for API architecture, design, implementation, or support [...]

TIMECODES
00:00 Intro
02:07 A story of API design & governance
04:17 The challenge of HTTP-centric API design
06:34 A unified method for API design
09:12 Examples/demo
15:10 A unified method for API design continued

Download slides and read the full abstract here:

RECOMMENDED BOOKS

#APIs #GraphQL #gRPC #REST #RESTapis #APIDesign #OpenAPI #AsyncAPI #Protobuff

Looking for a unique learning experience?

SUBSCRIBE TO OUR CHANNEL - new videos posted almost daily.

[stanislavtsybyshev]

That's somehow reminds me of UML and Rational set of code-generation tools from the 90s... That's all great, but what happens when your API need to evolve (the part seemingly missing from the demo)? You need to modify the ALPS definition, right? And because it is high-level, it naturally wont include the specifics of OpenAPI (or GraphQL, or protobuf, or whatever) - so you need to update ALPS, then regenerate API definitions one layer below (lets say OpenAPI or whatever), then (manually) carefully retrofit the all the details present in the previous version of OpenAPI in a new version of schema and so on.
I have a feeling this process may become quite cumbersome and the ALPS <-> OpenAPI will inevitably diverge...

[igboman]

I am struggling to see how this simplifies API design. It seems like adding another layer of more complication

[AhedEid]

"application-level profile semantics" is a new concept for me.

[webtel]

how can one generate correct graphql schema from description with no notion of nullability?

[JohnNecirRebellion]

This talk is about the concept of designing API without being stuck with HTTP or any protocols for transferring data.
The talk is about how it'll be easy for someone to implement an API in any specifications (REST, GraphQL, gRPC, etc.) without changing a lot of code when changing specifications mentioned.

So I think the tool presented here is not the whole, one-tool fix-all, solution. The tool demonstrates the statements I wrote above.

If you want a tool like that, then build yours that suit your needs. Or if you understand the talk, then you should try building APIs with a certain specification then switch specification and see the difference in how fewer line of codes/logic was changed.

[Wenugo]

As long as you don't want your OpenAPI-based HTTP to be RESTful?

[folie-nt]

The problem is that different teams are going to be working on different APIs and the design doc rapidly becomes out of date.

[LJCRIA]

How can we find that “unified” tool for generating?

[BruceArmstrong]

This is really nice one!, I can easily convert between the different tech like graphQL

[JumpyMcTwist]

What's that tool for proto files on 14:33?

[valour.se]

this is awesome, it will definitely going to save time.

[ThomasJoeisseint]

Maybe I missed something but I don't really understand how you can fully generate one API implementation from a generic (simpler) API description (ALPS), you would obviously lose some implementation details (like http codes, http methods...etc... taking openAPI as an example).
It's like saying you would use pseudo code to generate a Java or Clojure application, maybe you could but you would lose many of the interesting features each language as to offer, and certainly end up with something that Java or Clojure developers would find pretty bad ("Hmm yeah actually there is a better way to do that...") because you would need to use stuff that can be generically used by both in the same pseudo code.
So to summarize I guess you end up with big limitations and only using the common part of each implementation, which is rarely the determining factor in choosing that particular implementation (you most often choose it for some specificities that another doesn't propose).

the center in red being that simpler API description, using things that are commonly present in each implementation but losing many of the uncommon/specific parts of each.

On the contrary I think you could use ALPS the other way around, to be fully generated from the implementation description and easily read by someone not used to this specific implementation but fluent in ALPS.

[kapilshekhar]

Great Idea! But .... everything is an abstraction of an abstraction of an abstraction of an abstraction of an ab

[Lior_Banai]

So we end with more languages instead of less.. Not good.

[wec]

I could actually see myself using this. After getting the domains right, try to nail the APIs on a high level using ALPS. Hm.

[keribrahim]

This one is cool, should let my product guy know about this

[charifzahlan]

^^ I also call my linux box penguin.
Interesting talk and implementation!