What Is a REST API and Why SaaS Teams Use Them

We addressed several API types (including REST) in a recent overview post. In this post, we'll look at REST APIs in more detail.

A REST API is an API (application programming interface) that follows REST design principles. REST stands for representational state transfer. Let's break this down:

• Representational: Any content we can name is a resource. For example, https://sampleapi.com/customers is a resource. A resource, as defined with a certain format (such as XML or JSON) is a resource representation. REST provides the representation of the resource to the client.
• State Transfer: Each request from the client to the server must contain all the information needed to parse and complete that request. This information includes such things as the API key, user agent, and HTTP version. This information is referred to as the session state, and can vary by client and request. For REST, the state must be transferred with every request and cannot be stored on the server. We might think of it as the server meeting the client for the first time every time.

REST APIs are also commonly called RESTful APIs.

The history of REST APIs

The REST API is not quite as old as the web, being first defined in 2000 by Dr. Roy Fielding in his doctoral dissertation. Before that time, the web didn't have standards for designing or using APIs, though there were any number of APIs (such as SOAP) in use.

In simple terms, Fielding defined REST design principles to allow two servers to communicate and exchange data. An essential element of this was that the servers could be anywhere, but if they could talk to each other via HTTP, REST would work.

It only took a few years from the dissertation's publication for REST APIs to become essential to doing business on the web. And even though newer API design patterns are available today, REST continues to be the default for building SaaS APIs.

How REST APIs work and what they are used for

REST APIs use HTTP, the standard transfer protocol for the web, to enable data import and export between apps/systems. They use HTTP verbs (GET, POST, PUT/PATCH, and DELETE) to do this. These verbs support all standard CRUD (create, read, update, and delete) data operations.

REST APIs require authentication (auth). This can be done using basic auth (not recommended), an API key passed in as an HTTP header (common), or OAuth 2.0 (best option).

Let's say that the REST API is available at https://sampleapi.com/. Here's a sample of how we can interact with the API using HTTP verbs:

• To get a list of customers from this API, you use GET with https://sampleapi.com/customers.
• To create a new customer via the API, you use POST with https://sampleapi.com/customers.
• You can also get the details of a customer record using GET with https://sampleapi.com/customers/{customer-id}.
• To update a customer record, you use POST (or PUT/PATCH) with https://sampleapi.com/customers/{customer-id}.
• Finally, to delete a customer record, you use DELETE with https://sampleapi.com/customers/{customer-id} .

Here is what it takes to interact with our sample API to create a new customer record using JSON.

Why SaaS teams and products use REST APIs

Did we mention that REST APIs use the HTTP protocol for data transfer? Yes, the same protocol that drives access to the billions of web pages people view daily. As a result, many developers find REST APIs attractive because they are already familiar with HTTP.

And it's easy to work with a REST API. Devs can use curl, Postman, or any number of HTTP clients to set up requests with a REST API in a few seconds.

Adding to the overall ease of use, many REST APIs follow OpenAPI standards – making it straightforward for developers to work with an API without first studying extensive technical documentation.

What are REST API design principles?

REST APIs can be built with just about any programming language, but they must follow these design principles:

• Uniform interface. Invoking a given URI (uniform resource indicator) must result in a consistent action. For example, using POST with https://sampleapi.com/accounts should always create a new account record.
• Client-server decoupling. The client app doesn't need to know anything about the server app other than the URI of the resource. The server app, for its part, sends the client app the requested data. The client doesn't care if the server is running PHP, python, .NET, or whatever.
• Statelessness. Every request must include all necessary instructions for processing it. Nothing with reference to the client state is stored on the server. This means that each HTTP request is completely self-contained and does not depend on the server to remember anything about this session or prior sessions.
• Caching. As feasible, both the client app and the server app should cache data to improve performance and scalability. Caching is the ability to store copies of data at different places along the request-response path.
• Layered architecture. Neither the client app nor the server app should be able to tell if it is communicating directly with the other app or some intermediate system or layer.
• Code runs on-demand. REST APIs are designed for data transfer, not executable code. But under certain conditions, they can transfer code, but it should only run on-demand.

What are best practices for setting up REST APIs?

Though the design principles define REST APIs, there is still a lot of room for variability when it comes to implementing them. Here are some best practices to ensure that your REST API is useful for developers to use as possible.

• Use nouns in paths. REST APIs already use the HTTP verbs (methods). To avoid confusion, ensure there aren't any verbs in your endpoints. Set up an endpoint to create customer records as /customers and not /createCustomers/.
• Stick with plurals. Going back to the /customers endpoint, you should use the plural even if you are creating a single customer record. Then, when accessing a single customer record, your endpoint shows as /customers/2562 (making it clear that the single record is part of the customers data collection).
• Document your API. Using OpenAPI makes things simple for those devs who use your API. If you don't go with OpenAPI, use another tool, such as Swagger, to document your API.
• Use real examples. However you document your API, use real examples for each API endpoint. This is critically important if your API needs to work with binary files.
• Keep errors simple. REST APIs use HTTP. That means you should use the standard HTTP error codes. We're all familiar with 403 (forbidden) and 404 (not found), but there are dozens of codes in all.

How do REST APIs work with integrations?

REST APIs generally work well with integrations. That said, here are some things to keep in mind when building integrations with REST APIs.

• Not every API that is called a REST API follows the design principles. These "REST-like" APIs may require additional work for integrations.
• Because REST APIs are stateless, you'll need to ensure that the integration manages authentication.
• Depending on your customers' needs, you may need to set up dynamic endpoints in your API for each customer.

The future of REST APIs

REST APIs have been around for more than twenty years, and they've been the dominant web app API for more than ten years. There are good reasons for this, including their reliance on HTTP, which makes them familiar to web devs who haven't previously worked with APIs.

And while REST APIs have been challenged by newer web API types such as GraphQL, their functionality and capabilities are too well-suited to the market to disappear any time soon.

For more content on Rest APIs and other integration topics, check out our guide to API integrations.