API Style Choices

Sharing is Caring

Application Programming Interfaces (API) have existed in some form or another for quite a while. APIs have been important because they allow companies to have different applications communicate.

APIs come in many different styles and types. Before running into a style we need to understand the different options and the trade offs that we are making.

CORBA

In the 1990s, we had two different standards. In 1991, Common Object Request Broker Architecture (CORBA) was launched. It was one of the first official standards on the scene. CORBAs claim to fame is that it had a distributed object model.

CORBA had a huge impact on the way Java and the web were created. It didn’t really provide a way to abstract away things and generally things were implemented inconsistently.

In 2022, it’s fair to say that CORBA is dead. I think the main cause of its failure is that Microsoft didn’t embrace it. Microsoft pushed their technology called Distributed Component Object Model which never really worked well either.

RPC

Remote Procedure Call (RPC) is an architectural style for distributed systems. The procedures don’t need to run on the local machine. The procedure could run on a remote machine in the system even though it appears like it’s running on a local machine.

There are more modern variations of RPC called gPRC. gRPC uses HTTP/2 for transport and allows for connecting services in a microservice like way or allowing mobile devices to call backend services. I like that it can potentially generate a definition file that stubs out the implementation.

When calling a remote procedure it should be easy. This easy calling comes with a cost though – the client and the server end up tightly bound and changing one can easily break the other.

SOAP

SOAP or Simple Object Access Protocol connects processes through HTTP (mostly!) and the XML data format. SOAP follows preset standards like a messaging structure, encoding rules, and conventions for procedure requests and responses.

What I like about SOAP is it allows us expose application logic instead of just data as services. SOAP focuses on accessing named operations instead of just simple CRUD.

SOAP has great built-in error handling. Most of the time a request includes valuable error information with standardized error codes.

One thing to keep in mind, is that SOAP uses a WSDL file to create a contract for the caller. SOAP style APIs and architecture are still use but they are usually only used for internal enterprise systems or for services called by trusted partners.

If the WSDL file is malformed in any way, it’s almost impossible to use most of the features of SOAP. For the most part, the golden rule should be always prefer SOAP over REST for any new APIs you are developing.

The blog article How to Connect to a SOAP API from Nodejs covers some techniques on how to use SOAP.

REST

REST or REpresentational State Transfer is an API architecture style that uses a uniform interface. REST is designed to make optimal use of the HTTP protocol and infrastructures. It uses servers, caches, and proxies with ease.

An easy way to explain REST is to say that it uses all of the ideas that worked well for the web and applied them to web services (or APIs)!

The most popular data type used with REST is JSON, but XML and other formats are usually supported.

GraphQL

GraphQL is a relatively new API technology that focuses on making it easier for clients to request and use data. GraphQL was developed in 2015 by Facebook.

GraphQL calls itself a query language for the API. A GraphQL service is created by defining types and fields on the types and then providing functions for each field.

GraphQL fixes quite a few potential problems that REST has a user – usually many API calls have to be done to do anything useful in a system. REST requires a lot of potential bandwidth because a lot of the data that is returned may not be useful resulting in needless expense or higher potential latency.

Wrapping It up

There are a lot of different variations of API standards to adopt, and the standards we choose can have a dramatic result in it’s adoption and use.

REST, GraphQL are the flavours of choice today. REST can require an incredible amount of upfront design work to make it easy to consume. GraphQL requires a lot of of additional properties or fields to make it queryable.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.