REST And Hypermedia And GraphQL And gRPC And Event-Driven

API folks are great at being passionate about the technologies they believe in. This is great for them, but it isn’t always great for the folks who aren’t quite as passionate and are just working to understand the API landscape and make sense of the different patterns, services, and tooling out there. One of the areas I’ve been heavily investing in as part of my API industry research over the last couple of years is to help people understand how they can invest in a diverse API toolbox, and develop the awareness they need to be successful in designing, developing, and delivering APIs at scale, for a variety of use cases. Counteracting some of the more vendor focused storytelling in the space that works to confuse, distort, and shame folks for their approach to delivering APIs—providing a more pragmatic view of how we should doing APIs.

I’ve had a front row seat for several new technologies to emerge within the API sector, and with each one there is always an aggressive group of technologists who like to employ a pretty old and tired API trope that the new technology is the future, and what already is represent the wrong, or out of date way of doing things. It is what vendors do to dethrone what came before, and try to get a foothold within markets. Playing on a popular belief that technology is perpetually moving faster than ever before, and you have to always be buying into what is next, otherwise you will miss out on the future, and be eaten alive by your competition. If a vendor, blogger, or analyst is saying that one API technology will completely replace another API technology, and the previous way is the wrong way, I recommend moving on, finding other sources of information to educate yourself and inform your organization’s overall API strategy.

REST Is Where You Begin
The API haters love to bash on RESTful design practices. However, the reality of the matter is that REST is where you should begin your journey, and will remain a staple of the API sector. Sure, REST has many flaws and shortcomings, but it still is the lowest cost, simplest, and most ubiquitous approach to delivering APIs that will be usable by the widest possible audience. If you are new to APIs, REST is where you should be spending your time learning about the API landscape, and understanding what is possible. The number of REST APIs, also known as web or HTTP APIs dwarfs the number of other API design patterns in use. Ignore all the REST API haters, and make sure you properly educate yourself about why it is the dominant API design pattern, and how it will help you lay the foundation you need for your API platform.

Hypermedia Reflects the Web
Another API design pattern people love to hate on is what is known as HATEOS or simple hypermedia. Ironically, many hypermedia believers have also fallen prey to the same trope, and declared that hypermedia is the one right way of delivering APIs, and you should ignore all other patterns. In reality, hypermedia is extremely useful for specific types of APIs that rely on affordances we take for granted from the web. Hypermedia makes sense for content centric and media focused APIs. You’ll find TV, movie, news, and other media APIs employing hypermedia very successfully, providing a very rich developer experience, providing links, formal media types, and other structural elements that help make for a better API. Like other API patterns, hypermedia will begin to diminish in value for some types of APIs, and will prove to be challenging for newer developers who may not be familiar with the increased complexity and robustness of the approach to delivering APIs. Hypermedia is definitely a pattern you should be learning about to add and round off your API design toolbox.

Schema Powered GraphQL
GraphQL is another approach to APIs that people love to say is going to replace REST entirely, but in reality it is just another approach to have in your toolbox, helping you cater to the specific needs of a known audience of consumers who need more access and control over the schema behind an API. GraphQL excels at providing access to complex backend database schema, and goes a long ways to empowering developers who are familiar with the schema to move quicker in delivering applications. Like hypermedia, GraphQL can prove to be a challenge for new users who are not familiar with the underlying schema, and why some of the added complexity that exists. GraphQL is not for every API project, and should live alongside other design patterns in your diverse API toolbox. When you have the right project, and the right developer audience, you should be looking at GraphQL, but make sure your audience is up to speed on your schema and tooling, and the reasons for putting to use are in alignment between the platform and consumers.

gRPC Delivering Performance
An industrial grade approach to delivering APIs that has gained in popularity and adoption lately is gRPC, and open standard out of Google. gRPC excels at delivering digital resources at scale internally and in B2B environments. gRPC tends to take advantage of HTTP/2, and represents the evolution of the HTTP standard for many. It is fast. Much faster than REST over HTTP 1.1. If performance and volume are major concerns, then you should be considering gRPC. However, like hypermedia and GraphQL there is a cognitive load associated with getting up and going for some developers, and the design patterns in play aren’t always as intuitive, and easy to learn as REST. gRPC has its place in the toolbox, and is something you should be thinking about as you develop your toolbox, and your API strategy. Adding another valuable API pattern to your arsenal, allowing you to think critically about which tool is right for the job you have in front of you.

Event-Driven Approaches
Finally, there area number of event-driven approaches to doing APIs, ranging from Webhooks to Kafka, providing developers with a variety of patterns to apply when looking to make their API infrastructure more resilient, real-time, and responsive to consumers needs. If you are looking to get your feet wet in the event-driven space, I recommend beginning with web hooks, and augmenting your HTTP APIs with outbound hooks that push data to consumers when the most meaningful events occur across a platform. If you are looking to dive right into the event-driven space and you have the expertise and bandwidth to properly evaluate new technologies, I recommend firing up Kafka, NATS, or the other industrial grade solutions available on the market today. Event-driven approaches to delivering API infrastructure reflect the future, and are present across the most mature API providers out there. It is definitely where you should be headed with your API operations, but how you get there may take time, and require a significant amount of learning before you can effectively get what you are looking done.

Invest In Your API Toolbox
If you truly want to be an API professional, then get to work developing your API toolbox, and equipping it with a range of solutions. Don’t spend time listening to the API haters, and the most dogmatic voices out there. Don’t let yourself be restricted by any single pattern, or be held prisoner by your own dogmatic beliefs. There is no single right way of doing APIs, there are only a suite of patterns and approaches for you to consider applying to the API challenge you face. As you are reading blogs about APIs, remember it is never REST vs. GraphQL, or Kafka vs REST, or Hypermedia vs. REST — it is REST and Hypermedia and GraphQL and gRPC and event-driven, as well as any other useful patterns you might come across and can successfully apply to your operations. When learning about any of the technologies I’ve discussed, make sure you spend the time to find the right sources of information regarding the pros and cons of each approach, and regularly take time to step back and consider the bigger picture.

Doing APIs well takes experience. Being able to competently switch from technology to technology takes confidence, and an awareness of the strengths and weaknesses of each solution. You will never solve your business problems by jumping on bandwagons and subscribing to the hype in the API space. It can be hard to truly see what is hype and what is reality sometimes, but with the right amount of work, you can develop your own sense for what matters. Develop your network of trusted sources of information, and spend time asking questions of providers, practitioners, and analysts about not just the happy paths, but also the less than happy paths that exist when employing any particular technology. Invest in your teams knowledge. Invest in your toolbox. Build prototypes and proofs of concepts. Don’t just make decisions on the latest wave of hype and excitement coming from the online API boombox—eventually you will find your way forward.