There are different kinds of API styles. As a software architect, you should make a choice between them for each API you design. This might seem to be an easy choice, but it isn't. Whichever you choose, your choice will have consequences. These can be good or bad. It all depends on your markmanship. Your skills in using the API style best suited for the situation at hand.
The obvious choice today is REST. It used to be RPC, but for several years now it has been REST. Some say that a mention of REST in your offerings will get you an automated checkmark on API choice. And with it, increased chances of getting the job.
REST, though, is designed for specific usage patterns. For others, REST may not be the best choice. Roy Fielding, the undisputed father of REST, would be the first to point that out. In his famous dissertation, which is where he first introduced REST, he says so. It's in the 5.1.5 Uniform Interface section. Here follows two quotes from that section:
"The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components."
"The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction."
Notice that Fielding himself rates REST's uniform interface as its most distinguishing characteristic. He also says this. "A uniform interface degrades efficiency in comparison to one specific to an application's needs".
Chris Bailey talked about this in a presentation at the Index conference in San Fransisco in 2018. He also gave a clear example of this, using the Starwars REST API (Swapi). He wanted to display Luke Skywalker together with a list of the films in which he had occurred. This was all he wanted, nothing else:
We have marked out the parts of the response in which he was interested. As you can see, it's the name of Luke and a list of links to the films in which he was involved. The response contained other pieces of information in which he had no interest. Many refer to this as "overfetching". This is typical of REST because of its uniform interface. REST treats all consumers the same and always returns the entire resource, no matter how much or how little of it the consumer needs. This is also one aspect of the "degrading efficiency" that Fielding talks about. In many situations, in which bandwidth is low or device capacity small, this can be quite harmful.
Next, he sent a query for the first of the five films listed. This was easy, because the first response contained the entire URL for that query. Here's the response:
As in the first response, we have marked out the parts Bailey was interested in. It's the name of the film, nothing else, so the overfetching here is enormous.
This response gave Bailey the name of the first film. He now had to make four other queries, one for each of the other four films. We're not showing these queries, because they would bring nothing new to the table.
You have seen that the overfetching in this example is enourmous. So little information is wanted, and so much information has been sent.
There's also a lot of underfetching. This is when the server doesn't return the entire response in the first network roundtrip. In most cases, this is even worse, because it causes even more efficiency degrading than overfetching. To collect the small dataset that Bailey wanted, REST needed six network roundtrips. The lack of performance in that could be very harmful to many applications. Not to speak of the user frustration it may feed.
Both RPC and GraphQL allow creation of "interfaces specific to an application needs". In fact, allow is too weak a word here. With RPC or GraphQL, developers should design interfaces customized for the application's needs. In both cases, just one network roundtrip would fetch the entire result. Both would deliver the exact responses needed. There would be no underfetching and no overfetching.
This is not to say that REST is bad. Far from it! REST is a wonderful architectural style for its right uses. For the wrong uses, there are often much better options.
This is one of the highlights of the Certified Software Architect Microsoft Platform program. It's an important highlight. We're digging deep into it, trying to give you the best tools for it possible.
