Shawn Wildermuth

Author, Teacher, and Filmmaker
.NET Foundation Board Member

Should We Be Thinking of APIs in a more Polyglot Way?

Should We Be Thinking of APIs in a more Polyglot Way?

Writing APIs have been a big part of my career. I've written COM, DCOM, XML based APIs, ISAPI Filters, SOAP, REST, gRPC, and others. A lot of this time a new technology in writing APIs has been chasing the new ‘cool’ technology that would fix everything.

The chase has always been lost cause. APIs, like most things in computer science, are a set of compromises. I think, for the first time in my career, we're entering a time when we don't need a ‘winner’ but need to stop thinking about APIs as a better hammer.

While Microsoft's announcement of embracing gRPC and GraphQL both came as surprises, I'm still flummoxed by some developer's insistence that some new technology is the one to rule them all. That's made me start thinking about how we can think of APIs in a different way.

These days, I see many applications that are glued together by REST. I like REST, at least pragmatic REST. But it's not perfect for every case. This is exemplified in a question I get commonly about doing non-resource based calls with REST.

When I started digging into gRPC, this was my big question. Was gRPC the ‘new best way’ to build APIs? I quickly realized that gRPC was great for certain use-cases. This forced me to think about APIs in a different way. My guess is that I'm not the first one to think about it in this way. And perhaps there is a better term than “Polyglot API”, but for now that's what I'm calling it.

The idea is that you'd want to use each API technology when it's the right tool. That does mean that as developers we need to understand more than one type of API, but I think we're up to the challenge. For example, I think that in a typical environment where you had REST, you might replace it in a number of cases with other technologies as seen in this quick video:

While this list isn't comprehensive, this is my first take in where I'd use each of these technologies:

REST: Resource based or CRUD-like functionality. If you're writing forms-over-data, REST is still your best friend.
GraphQL: I think of GraphQL as a great API for when you have amorphous data or amorphous queries. Reporting Services is a good example of this, though you could imaging it useful in a number of places like product searches.
SignalR1: Connection-based APIs when you need a connection to clients. This is especially good for multicasting messages to multiple clients. For example chat apps, change notification, etc.
gRPC: Also connection based, but better for data streaming and low-hardware scenarios. Has low serialization requirements (unlike JSON). Requires strong contracts so that intra-datacenter apps or microservices are a common case.

1 SignalR is not as cross platform as the rest of these types, but is moving in that direction.

I don't think there are any black lines that define these technologies, but I do think that we'll certainly need more than one type of API in most medium to large applications.

How am I wrong? I'd love to learn what I'm missing. Let me know below.