In this podcast, the hosts discuss API design, including what makes a good API and why we often do REST wrong. They also explore the concept of HATEOAS and whether GraphQL is a solid choice. Other topics include the benefits of Neon, a serverless Postgres service, the advantages of hypermedia APIs, and the challenges of rewriting a music streaming app from a flash-based player to HTML5. They wrap up with plans for future episodes and sponsorship mentions.
Read more
AI Summary
AI Chapters
Episode notes
auto_awesome
Podcast summary created with Snipd AI
Quick takeaways
Building a Hypermedia API empowers clients to dynamically navigate and interact with the API.
GraphQL and gRPC may not offer the same level of flexibility and scalability as Hypermedia APIs.
Many so-called Restful APIs today are actually HTTP APIs, lacking the Hypermedia component.
The adoption of Hypermedia APIs has been hindered by the additional effort required in initial design and the limited availability of practical Hypermedia formats.
Deep dives
Hypermedia API Design
When designing an API, one should prioritize building a Hypermedia API. Hypermedia APIs adhere to the concept of hypermedia as the engine of application state, where the server provides hypermedia controls in the response, allowing the client to navigate and interact with the API. Instead of relying on strict URL routes or hard-coded logic, a Hypermedia API empowers the client to dynamically utilize the provided links and instructions in the response.
GraphQL and gRPC Considerations
GraphQL and gRPC are alternative approaches to building APIs, yet they have limitations compared to Hypermedia APIs. GraphQL is often favored by front-end developers due to its flexibility and empowering nature. However, it may not align with the principles of Hypermedia and can result in improper usage of HTTP. gRPC, on the other hand, offers potential benefits, but may require heavy modifications and integration dependencies, thereby potentially deviating from a more simplified API design. In both cases, they may not offer the same level of flexibility and scalability as Hypermedia APIs.
Restful API vs. HTTP API
It is important to differentiate between Restful APIs and HTTP APIs. Restful APIs should ideally follow the principles outlined by Roy Fielding's dissertation on REST, including the adherence to the Hypermedia constraint. However, many so-called Restful APIs in common usage today are, in fact, HTTP APIs, as they often lack the Hypermedia component. These APIs typically require manual reading of documentation and do not fully leverage the benefits of Hypermedia-based interactions.
Challenges of Hypermedia API Adoption
The adoption of Hypermedia APIs has been relatively low compared to other approaches. One reason for this is that building a Hypermedia API requires additional effort in the initial design phase, as the server needs to provide hypermedia controls and the client must understand and utilize them. The limited availability of practical and easily implementable Hypermedia formats has also hindered adoption. However, Hypermedia APIs offer greater flexibility, scalability, and decoupling between the client and server, which can lead to more maintainable and adaptable API systems.
Benefits of using open API spec and Swagger
Open API and Swagger provide a convenient way to define APIs by generating clients and documenting the API structure. Open API allows for flexibility in defining representations and supports multiple formats like Protobuf and XML. However, one limitation is that the documentation can be sparse and lack comprehensive information.
Exploring HTTP as an ABI definition
HTTP can be seen as a lower-level calling convention that defines the mechanics of how API requests are made. Taking advantage of HTTP features like the Prefer header and the query method can provide more flexibility in API design. Additionally, introducing new headers, methods, and functionalities can help evolve APIs over time.
Considerations for starting a public web API
When starting a public web API, pragmatically using open API and Swagger can be a good choice for generating clients and providing initial documentation. However, it's important to have a long-term strategy for API evolution and consider other options like GraphQL if the API is tailored for front-end developers. It's also essential to invest in comprehensive documentation to ensure developers have a clear understanding of the API's capabilities.
Unlocking the full potential of HTTP
Exploring HTTP specifications and experimenting with different functionalities can lead to a better understanding of its capabilities. Leveraging features like the Prefer header and developing new methods can provide more flexibility in API design. It's important for the industry to be more open to trying new ideas and contributing to the evolution of HTTP as a platform.
Jerod is back with another “It Depends” episode! This time he’s joined by Kris Brandow from Go Time and they’re talking all things API design. What makes a good API? Is GraphQL a solid choice? Why do we do REST wrong? And WTF does HATEOAS mean, anyway?
Changelog++ members save 10 minutes on this episode because they made the ads disappear. Join today!
Sponsors:
Neon – The fully managed serverless Postgres with a generous free tier. We separate storage and compute to offer autoscaling, branching, and bottomless storage.
Sentry – Get $100 towards your error monitoring with Sentry! Use the code changelog.
Fastly – Our bandwidth partner. Fastly powers fast, secure, and scalable digital experiences. Move beyond your content delivery network to their powerful edge cloud platform. Learn more at fastly.com
Fly.io – The home of Changelog.com — Deploy your apps and databases close to your users. In minutes you can run your Ruby, Go, Node, Deno, Python, or Elixir app (and databases!) all over the world. No ops required. Learn more at fly.io/changelog and check out the speedrun in their docs.
