The 5 Most Popular API Styles and What Sets them Apart

On the subject of use cases, it’s worth mentioning that APIs can be public, available to partners, or completely internal. This first differentiator sets the standard to many of the features and functionalities that will need development: how data is stored and shared, how credentials are handled, how much traffic the API needs to take, etc.

As you’ll see, the following architectural styles can be used in any of these three cases, but some combinations make more sense than others.

These are by far the most common APIs today and also the style we used to build WebScrapingAPI. The acronym stands for REpresentational State Transfer, and the style dictates that if you, as a client, make a request, the API will send back a representation of the state of the resource you asked for.

RESTful APIs are heavily based on the HTTP infrastructure. Since the web in general mainly uses HTTP, REST APIs already have an advantage since they’re easy to understand, integrate and use.

This style is also defined by a set of constraints that the API must respect. While this may sound like a hassle at first, the constraints ensure that the API behaves in a predictable and helpful manner. There are six in total, and they go like this:

• Uniform interface
• Stateless
• Cacheable
• Client-server
• Layered system
• Code on demand

We’ve published a whole article on these constraints on Medium, so check that out to get into the finer details regarding REST APIs.

If an API respects some of these constraints but not all, they can be called REST-like. For some use cases, the constraints may bring more trouble than benefits, which is why you might run into partial adoptions of the style.

SOAP, or Simple Object Access Protocol, relies heavily on XML. To use it, you have to adhere to strict standards regarding messaging structure, encoding rules, and handling requests and responses.

While very exact and expansive, SOAP APIs can be harder to get used to due to their markup language. Requests and responses can get pretty long and complex, making them a chore if you manually type the commands.

On the bright side, this style has the advantage of built-in error handling. If you run into a problem with the request, the response will contain a lot of valuable information that can help you find and correct the error.

This style is used for querying databases from client-side applications over HTTP. But, instead of sending several HTTP requests to different endpoints, you can POST a single “query” for all you need. In essence, the client describes what they need once, and the API does its best to retrieve that data.

A server operating under the GraphLQ architecture has a pre-made model (or schema) for the data that can be requested. So, when you make a request, the schema acts as a guideline on what you can ask for, how the information should be structured, and how you can interact with the server.

The advantage of this system is that users have a clear understanding of what they can get, so retrieving false data or running into an error is highly unlikely. The underlying principle is to put the client at the forefront and give them the best experience.

Similar to GraphLQ, Falcor APIs create a virtual JSON file that acts as a container for the data a client will receive after a request. This virtual file can be extended with every new piece of data the client needs. While this adds convenience, the file can become pretty big with time.

Luckily, you don’t have to retrieve the whole JSON file with every request. Instead, you can specify which parts you need at any moment and get those in the response. This works because the JSON file is published under an URL and links to different resources in the backend. Essentially, you can navigate the virtual file for the data you want.

This virtual layer between the client and the server helps connect the two while keeping both their architectures completely independent.

When you have few constraints to worry about, gRPC should be one of your first options when designing an API. It’s language-agnostic, platform-agnostic, and quite fast due to its use of Protocol Buffers (protobufs) to serialize data into binary streams. That data is then transferred through HTTP/2.

gRPC is well-suited for distributed systems. The most important aspect of the style is the procedures. You can run them on the local machine and remote devices. In both cases, calling a procedure is quick and straightforward.

One of the reasons why APIs are becoming popular is the advantages that separate microservices present over the classic single service software model. This way, each feature/microservice can be designed, developed, and updated separately without compromising other components. In that sense, gRPC is a great solution to tie it all together.

Also, since you can start a procedure remotely, it’s also a good fit for connecting mobile devices to backend services.

While this article has offered you an overview of the most common API architectural styles, it’s not enough to ensure that you pick the right one. It was essential for us as a team to have actual first-hand experience with as many examples as possible.

By experience, I mean both as a user and as a developer. After all, maybe there’s a style that you’re more familiar with, so it would be easier to build, but you have to put yourself in the end-user’s shoes and see how it works out for them.

A style isn’t something that you can just pick midway through development or switch later on. It’s a rulebook that dictates how the API takes shape. As such, it’s a big decision.

A first step you can take is to read the documentation for APIs already on the market and ideally test them. Previous experience with building APIs would also be a big plus.

If you’d like to see how we shaped WebScrapingAPI into the web scraping powerhouse that it is, why not check our documentation? Not all of its current features were present on release, either. Options like scraping REST API endpoints or files were added at the request of our users so remember: the architectural style is meant to give you a direction, but it’s your job to shape the API into something people will love.