What are REST APIs? HTTP API vs REST API

REST APIs are a common topic of conversation in the web development community. While many are debating how useful the APIs functionality is, others are simply trying to understand what it means and how REST relates to RESTful.

This is an important topic to know for developers jumping into the industry and will help you understand the modern state of client/server data architecture.

Today, we’ll demystify REST APIs by explaining what it is, how it’s different from other HTTP APIs, and for which applications you should use it with.

Master web APIs and Scala at the same time

Expand your back-end skills by creating project-ready functional HTTP APIs with Scala.

What is an HTTP API?#

A web API is a protocol that describes how your clients can access resources and what methods work with your architecture. These resources can be of a variety of media types like JavaScript or HTML elements, metadata, or images. You can essentially think of it as a translation guide from one technology to another. An HTTP API is an API that uses Hypertext Transfer Protocol as the communication protocol between the two systems. HTTP APIs expose endpoints as API gateways for HTTP requests to have access to a server.

For example, you use an HTTP API every time you set a Zoom meeting in your Google calendar. The API defines how Zoom can communicate directly with Google’s servers to embed a Zoom meeting into the event rather than having to copy and paste the meeting invitation into a field.

HTTP APIs is a broad category, meaning they come in various forms based on their target use case. HTTP APIs are further categorized by the architectural design principles used when they’re created. Most are used in hypermedia information systems or web development, but each has particular pros and cons.

Before we explore the popular REST API, let’s take a look at some of the common alternatives.

GraphQL API#

GraphQL API is the second most popular form of API and seeks to correct common problems with the REST API structure. It’s open-source and designed to hold data in a tree structure. The main difference is that the GraphQL API is more flexible than REST due to the way it handles data fetch requests. REST often over-fetches or under-fetches data if the data is of a slightly different type than what’s commonly requested. GraphQL API allows requests to call for the exact amount of data and type it needs, meaning you never have to send multiple requests or dump useless data.

Unfortunately, GraphQL API doesn’t support HTTP caching, so the same request must be reprocessed every time it’s sent.

Falcor API#

Falcor uses much of the REST API architecture with paths and references but automates much of the request structure. Instead of requesting from the server, Falcor allows you to simply use data as you need it. The system will determine if the data is client-side or server-side and then automatically retrieves it.

This dynamic approach makes Falcor great for video streaming applications like Netflix and other live update apps.

gRPC APIs#

Remote Procedure Control (RPC) is the precursor to REST APIs and has been around since the 1970s. The main difference between RPC and REST is that almost all of the processing is done by the server in RPC architectures. Recently, Google has updated RPC to the newer gRPC to use with their microservice architecture. gRPC uses Protobuf instead of JSON/XML and is built on HTTP 2 rather than HTTP 1.1.

This results in slower implementation than rest but increases message transmission speed by seven to ten times. gRPC is therefore used for systems that need to communicate often with other parts of the network.

What is a REST API?#

REST API stands for Representational State Transfer and is an architectural pattern for creating web services. It was developed by Roy Fielding in 2000 and has led to a growing collection of RESTful web services that follow the REST principles. Now, REST APIs see widespread use by application developers due to how simply it communicates with other machines over complex operations like COBRA, RPC, or Simple Object Access Protocol (SOAP).

REST is a ruleset that defines best practices for sharing data between clients and the server. It’s essentially a design style used when creating HTTP or other APIs that asks you to use CRUD functions only, regardless of the complexity. REST applications use HTTP methods like GET, POST, DELETE, and PUT. REST emphasizes the scalability of components and the simplicity of interfaces.

While it may seem counterintuitive to neglect a portion of your tools, it ultimately forces you to describe complex behaviors in simple terms. This leads to simpler methods and easier incorporation with other REST APIs.

Not all HTTP APIs are REST APIs. The API needs to meet the following architectural requirements to be considered a REST API:

• Client-server: REST applications have a server that manages application data and state. The server communicates with a client that handles the user interactions. A clear separation of concerns divides the two components. This means you can update and improve them in independent tracks.

• Stateless: Servers don’t maintain client state, clients manage their own application state. The client’s requests to the server contain all the information required to process them.

• Cacheable: servers must mark their responses as cacheable or not. Systems and clients can cache responses when convenient to improve performance. They also dispose of non-cacheable information, so no client uses stale data.

• Uniform interface: This is REST’s most well-known feature or rule. Fielding says “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.” REST services provide data as resources, with a consistent namespace.

• Layered system: Components in the system cannot see beyond their layer. This confined scope allows you to easily add load-balancers and proxies to improve authentication security or performance.

These constraints combine to create an application with strong strong boundaries and a clear separation of concerns. The client receives server data when requested. The client manipulates or displays the data. The client notifies the server of any state changes. REST APIs don’t conceal data from the client, only implementations.

Here’s an example of a RESTful API design completing a request/response loop:

//request
GET api/customers/10

//response
            {
           "customer":{
              "id":"10",
              "name": "customer name",
              "age": "28"
           }
        }

When to use REST APIs#

REST APIs are great for building general-purpose applications to be scalable in the future.

REST APIs are inherently decoupled from your client-side technology, meaning your application can work well on iOS, browser, or a device of the future with minimal difficulty. As a result, you can build your app with fewer concerns about being bound to particular client-side stacks and can focus on developing the app itself. RESTful APIs are therefore are more scalable and have a longer lifespan.

Caching also allows REST APIs to be more scalable by reducing the number of requests that the server needs to process for an in-demand resource. By caching the response and sending the cached response instead of reprocessing the request, RESTful services can process more requests with less resources.

When not to use REST#

Stateless architecture is both helpful and limiting for REST. On the one hand, stateless setups increase system lifespan by allowing you to change servers when it eventually becomes obsolete.

On the other, all requests need to include all data to complete the request in the message payload. This works well when it only needs a bit of data but quickly becomes unmanageable for complex requests. The trade-off with REST is between payload size and stateless flexibility.

It’s also important to note that you don’t have to strictly adhere to REST architecture in all things to gain the benefits. Using the principles of REST when they’re better suited is better than twisting an RPC style request into a REST-style.

Ultimately, REST is a helpful tool in your toolbelt and a good general rule to follow but it shouldn’t be your programming dogma.

What to learn next#

If you’re just starting out, this quick guide to REST APIs should give you some context on the popularity of this powerful system.

While a great tool for you, it’s important to keep your mind open to other API types so you can recognize when a situation calls for a non-REST solution. Back-end development is a common example of when pure functional or another type of HTTP service is more useful than RESTful HTTP.

To help you explore pure functional HTTP services, Educative has created the course Pure Functional HTTP APIs in Scala. This course helps you explore Scala’s functional capabilities by creating pure and impure services for databases. By the end, you’ll know some of the practical applications of Scala and know how to optimize your use of pure/impure services in professional HTTP APIs.

Happy learning!

Continue reading about APIs and HTTP#

• CRUD Operations Explained: create, read, update, delete

• How to use an API: fetch daily images with NASA’s Open API

• Behind the Screens: What happens when you type a URL in a browser