Kris Brandow, a prominent software engineer known for his work in the Go community, discusses the intricacies of API design. He and Jerod explore what makes a good API, questioning why REST is often misapplied. They dive into the debate between GraphQL and REST, highlighting the significance of hypermedia and how it affects client-server interactions. Kris also shares insights on the evolution of these technologies, addressing common misconceptions and emphasizing the need for clarity and documentation in API development.
Understanding the specific type of API and tailoring it to fit desired functionality and requirements.
Designing APIs with simplicity and consistency in mind improves the developer experience and makes APIs more intuitive and efficient to work with.
Technologies like GraphQL and gRPC may not be optimal choices for most API design scenarios.
Designing Hypermedia APIs that adhere to REST architectural style provides a more self-describing and discoverable API.
Deep dives
Different types of APIs
The podcast episode explores different types of APIs, such as web APIs, language APIs, operating system level APIs, and application binary interfaces (ABIs). The speaker discusses the importance of understanding the specific type of API one is designing or using and tailoring it to fit the desired functionality and requirements.
Designing APIs with simplicity and consistency
The podcast highlights the importance of designing APIs with simplicity and consistency in mind. The speaker emphasizes the benefits of having clear and predictable API naming conventions and consistent ways of accessing and manipulating data. It is suggested that these design principles can improve the developer experience and make APIs more intuitive and efficient to work with.
The limitations and criticisms of GraphQL and gRPC
The speaker expresses reservations and criticisms about technologies like GraphQL and gRPC. Concerns are raised about the overly specific use cases of these technologies and the perceived shortcomings in terms of fitting into the wider context of HTTP APIs or addressing the needs of the server and backend development communities. The speaker suggests that these technologies may not be optimal choices for most API design scenarios.
The advantages of Hypermedia APIs
The podcast discusses the benefits of designing Hypermedia APIs that adhere to the principles of the REST architectural style. By using hypermedia controls, such as links and forms, within the API responses, the server can guide the client and provide a more self-describing and discoverable API. The speaker highlights the importance of using external schemas and standardized definitions to convey the meaning and format of API data, enabling better flexibility and versioning.
The importance of using OpenAPI and Swagger for getting started with a public web API
OpenAPI and Swagger are commonly used to quickly get an API up and running, thanks to their ability to define the mechanics of how API calls are made. However, their documentation capabilities may fall short, leading to sparse and incomplete documentation.
The need for more exploration and experimentation in API design
API developers should not be afraid to experiment and try out new approaches to API design. This includes considering the use of different headers, methods, and protocols to improve the flexibility and evolvability of APIs.
The potential of HTTP as an ABI definition
HTTP can be thought of as a lower-level calling convention, much like an ABI in operating systems. By leveraging the various features and functionalities of HTTP, such as long polling, prefer headers, and the query method, developers can achieve more flexible and scalable API architectures.
The value of reading HTTP specifications
Reading the specifications of HTTP can provide developers with a deep understanding of the protocol and its capabilities. This knowledge allows for better utilization of HTTP's functionalities and leverages its potential for building powerful and adaptable API systems.
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.
