What Is a REST API? Examples, Uses, and Challenges

Originally published on July 9, 2020

Application programming interfaces (APIs) come in many shapes and sizes, which can make it pretty difficult for newcomers to understand what they are and how they can be used. At Postman we enjoy working with APIs. Seriously. We do. We believe APIs can be used for fun and business. To help illustrate how we see the world of APIs, we’ve crafted a new public collection of APIs that includes REST API examples for newbies to play with.

With so many differences in APIs, Postman aims to clarify the nuances of working with RESTful APIs, GraphQL APIs, as well as the original format of SOAP, making it an ideal place to learn about how all HTTP APIs work (and don’t work) with real-world API examples. Since REST APIs are the backbone of the web, mobile, and device applications today, it’s important to have a full understanding of what they are.

Related: The Different Types of APIs

What is a REST API?

A REST API, also known as a RESTful API, is a simple, uniform interface that is used to make data, content, algorithms, media, and other digital resources available through web URLs. REST APIs are the most common APIs used across the web today.

History of REST APIs

Related: The History of APIs

Before REST, most developers had to deal with SOAP to integrate APIs. SOAP was notorious for being complex to build, use, and debug. Fortunately, a group of developers, led by Roy Fielding, created REST—changing the API landscape forever.

Here’s the historical timeline of REST APIs:

• Before REST: Developers used SOAP to integrate APIs by handwriting an XML document with a Remote Procedure Call (RPC) in the body. Then, developers would specify the endpoint and POST their SOAP envelope to that endpoint.
• 2000: A group of developers, including Roy Fielding, decided to create a standard so any one server can talk to any other server. He defined the constraints for REST APIs. Since these rules are universal, it is simpler for developers to integrate necessary software.
• 2002: In 2002, eBay built its REST API, expanding its market to any site that could access its API. As a result, it caught the attention of Amazon, another e-commerce giant, who announced their API in 2002.
• 2004-2006: In 2004, Flickr then launched their RESTful API, enabling bloggers to easily embed images onto their sites as well as their social media feeds. Then, Facebook and Twitter both released their APIs two years later when they realized a large number of developers were scraping the sites and creating “Frankenstein” APIs.
• 2006-Now: Today, developers have embraced RESTful APIs fully – using them to add functionality within their websites and applications. Postman simplifies the process of building an API and streamlines collaboration so you can create APIs faster.

What are REST API standards, and why are they important?

REST API standards are the common language for our digital world. They not only provide a consistent way for developers to produce and consume APIs, but also improve the health and performance of applications that rely on them.

To make an API service RESTful, six guiding constraints must be satisfied:

Use of a uniform interface (UI)

To have a uniform interface, multiple architectural constraints are required to guide the behavior of components. Additionally, resources should be unique so they are identifiable through a single URL.

Client-server based

The uniform interface separates user concerns from data storage concerns. The client’s domain concerns UI and request-gathering, while the server’s domain concerns focus on data access, workload management, and security. The separation of client and server enables each to be developed and enhanced independently of the other.

Stateless operations

Request from client to server must contain all of the information necessary so that the server can understand and process it accordingly. The server can’t hold any information about the client state.

RESTful resource caching

Data within a response to a request must be labeled as cacheable or non-cacheable.

Layered system

REST allows for an architecture composed of hierarchical layers. In doing so, each component cannot see beyond the immediate layer with which they are interacting.

Code on demand

Because REST APIs download and execute code in the form of applets or scripts, there’s more client functionality. Oftentimes, a server will send back a static representation of resources in the form of XML or JSON. Servers can also send executable codes to the client when necessary.

How do REST APIs work?

Related: Use the Postman REST client

To understand how REST APIs work, it is critical to understand resources. A resource can be any information that could be named, such as a document or image, a collection of other resources, a non-virtual object, and more. Meanwhile, REST uses a resource identifier to recognize the specific resource involved in an interaction between components.

The method is the type of request you send to the server. The four main resource methods that are associated with REST APIs are:

1. GET: This method allows for the server to find the data you requested and sends it back to you.
2. PUT: If you perform the ‘PUT’ request, then the server will update an entry in the database.
3. POST: This method permits the server to create a new entry in the database.
4. DELETE: This method allows the server to delete an entry in the database.

REST vs. SOAP APIs

Related: What is a SOAP API?

There has always been a debate in the application programming interface (API) industry about SOAP vs. REST. SOAP and REST are two different approaches for building APIs. SOAP is considered a protocol, while REST is considered a set of guidelines. REST allows for flexible API development using methods like JSON, URLs, and HTTP, while SOAP uses XML for sending data. To decide which architectural style is right for you, it is critical to know the good and the bad of building a proper design when planning for your next API.

Simple Object Access Protocol (SOAP) helps define messages exchanged between systems and used by applications. In contrast to REST, SOAP is an actual protocol that provides you with stricter detail about what an API does. Even though SOAP may not be a suitable choice for newer mobile developers, it provides a solid foundation for enterprise resources integrations. The main takeaway here is that SOAP provides a solid, reliable pattern you can use when you don’t require a more date-centric API design pattern like REST.

REpresentational State Transfer (REST) is a software architectural style of delivering APIs dependent on the HTTP specification the web is built upon. REST APIs utilize the uniform resource locator (URL) to make data available using the web. This helps to ultimately maximize usage of HTTP methods, headers, and other essential web building blocks. Unlike SOAP, REST is a common starting place for most teams when they begin investing in APIs because it provides a simple and widely recognized set of design patterns.

What are REST APIs used for?

One of the key advantages of REST is that they provide a lot of flexibility, which enables you to do more with this particular API. Listed below are examples of what REST APIs are useful for:

Cloud applications

REST APIs are useful in cloud applications because their calls are stateless. If something fails, stateless components can smoothly redeploy and scale to accommodate load changes. Document sharing, storage, finance and accounting, customer relationship management (CRM), inventory control, and gathering information are some of the jobs performed with cloud-based applications.

Cloud services

REST is also helpful in cloud services because you’d need to control how the URL is decoded to bind to a service through an API. That being said, cloud computing and microservices will undoubtedly make RESTful API design the rule of the future.

Web use 

Since REST is not tied to client-side technology, these APIs can be accessible from a client-side web project, an iOS app, an IoT device, or a Windows Phone. You are able to build the infrastructure for your organization without worrying about being stuck to a particular client-side stack.

The benefits of using REST APIs

Related: Use the REST API Basics Template

REST is preferable to SOAP for several reasons. Here are a few advantages that REST APIs have:

• Scalability: Due to the separation between client and server, the product can be scaled by development teams without much difficulty.
• Flexibility and Portability: Since REST-style APIs require data from one of the requests to be sent properly, it’s possible to perform a migration from one server to another. It’s also possible to carry out changes on the database at any time.
• Independence: With the separation between client and server, the protocol makes it easier for developments across a project to take place independently. REST APIs are also adaptable to the working syntax and platform, which offers opportunities to test several environments at a time while developing.
• Lightweight: REST APIs are lightweight and fast, as they utilize the HTTP standard that supports multiple formats including JSON, XML, and HTML. This feature makes it ideal for mobile app projects, IoT devices, and much more.

Challenges of using REST APIs

Along with design and architectural constraints, individuals will have to deal with some challenges when using REST APIs. These challenges may include:

REST endpoint consensus 

It doesn’t matter how you format your URLs, but consistency across your API is crucial. Unfortunately, the number of combinations increases further with more complex operations. As a result, consistency can be difficult to achieve on large codebases with many developers.

REST API versioning 

API versioning is the practice of creating multiple versions of an API to accommodate changes or updates without disrupting consumers. To prevent compatibility issues, APIs are often versioned. However, old endpoints remain active, which leads to an increase in workload, as multiple APIs are maintained.

REST API authentication

API authentication will vary depending on the context of its use. Some third-party applications are considered to be logged-in users with specific rights and permissions. Other third-party applications can be used by registered users where they can only access their data such as looking for email or documents. There could be upwards of 20 different authorization approaches in use, dramatically increasing the difficulty of ever getting to make your first API call. With so much friction from the start, developers sometimes end up walking away.

Four common authentication methods include:

HTTP authentication

HTTP provides authentication schemes for REST API implementation. Two common schemes are:

• Basic authentication: HTTP basic authentication (BA) is a simple technique for controlling access to web resources. It doesn’t require cookies, session identifiers, or login pages. Instead, it uses standard fields in the HTTP header.
• Bearer authentication: Bearer authentication, also known as token authentication, is an HTTP authentication scheme that involves the use of bearer tokens for security.

API keys

One way to authenticate REST APIs is with API keys. When a client connects to a server for the first time, it is given a unique identifier. This unique API key is then utilized for authentication on every subsequent request to retrieve resources. It’s important to note that API keys have security risks because they must be transmitted with each request and can therefore be intercepted.

OAuth

OAuth is a security protocol that offers highly secure login access to any system by combining passwords and tokens. The authorization process starts with the server requesting a password, followed by an additional token to complete the process.

REST API security 

Even though RESTful APIs provide a simpler way to access and manipulate your application, security issues can still happen. For example, a client can send thousands of requests every second and crash your server. Other REST API security challenges include:

• Lack of proper authentication
• Absence of rate limiting and throttling
• Failure to encrypt payload data
• Incorrect implementation of HTTPS
• Weak API keys that are easily compromised

Multiple requests and unnecessary data

A response can contain more data than you need or require further requests to access all of the data.

REST API best practices

Adhering to these best practices in REST API design not only ensures smoother communication between servers and clients, but also enhances security, maintainability, and performance.

Use HTTP status codes correctly

It’s important to use the HTTP status code that is best aligned with the outcome of the request, as this information helps the API client know how to proceed.

Common HTTP status codes include:

• 200 OK: Indicates that the request has succeeded and the response body contains the requested resource.
• 404 Not Found: Indicates that the server cannot find the requested resource, often due to a mistyped URL or a resource that has been moved or deleted.
• 400 Bad Request: Signifies that the server cannot process the request due to a client error, such as invalid syntax or missing required parameters in the request.
• 500 Internal Server Error: Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request, typically a server-side issue beyond the client’s control.
• 302 Found (Moved Temporarily): Indicates that the requested resource has been temporarily moved to a different URL. The client should issue another request to the new URL provided in the response header.
• 401 Unauthorized: Signifies that the request requires user authentication, but the client has not provided valid credentials or has not yet authenticated.

Provide informative error messages

Error messages should be clear and descriptive, and they should include information about how to fix the problem (if possible). This helps the API’s consumer understand the problem and know how to fix it.

Secure your API

It’s crucial to implement API security measures—such as input sanitization, authentication, and role-based access control—to protect your API and user data.

Version your API

API versioning is used to manage changes and maintain compatibility with older versions of your API. It helps prevent breaking changes for existing users while allowing for evolution and improvement.

Document your API

Provide comprehensive, easy-to-read API documentation that includes examples of requests and responses, authentication details, and error codes.

Allow filtering, sorting, and pagination

REST APIs may slow down or crash when they try to return too much data at once. This can be avoided by using filtering and pagination. Filtering narrows down search results and pagination returns only small amounts of data. Both strategies improve performance and by preventing system overload.

Use instead of verbs in endpoint paths

HTTP methods are verbs, so it’s best to use nouns instead of verbs in endpoint paths.  The pathname should represent the entity that the API endpoint is retrieving or manipulating, such as /product. Including verbs in the pathname will make it unnecessarily long without conveying new information.

REST API examples

Now that you understand what a REST API is, let’s look at some examples:

Amazon S3

With many top-tier companies offering these services, the use of REST APIs for artificial intelligence, data science, and machine learning applications is on the rise. AWS AI Services from Amazon allows developers to incorporate AI functionality into their applications for a more adaptive and intelligent interaction. This can also help to secure data exchange between systems by detecting potential security vulnerabilities.

Twitter

With 450 million monthly active users, Twitter has an enormous reach in the realm of social media. For developers, the Twitter API offers a way to integrate Twitter’s functionality and promote their applications through the platform.

Using the Twitter API, developers can streamline the registration process by leveraging Twitter’s identification system. The API also enables the display of tweets to users based on criteria such as location or trending hashtags, as well as effective marketing using Twitter’s data.

Instagram

The Instagram Basic Display API provides developers with access to profile data, images, and videos on the platform. This allows developers to build apps that integrate user data from Instagram into their own products. Additionally, you can use the Instagram API collection for professional accounts, enabling users to manage their online activities.

Plaid

The growing marketplace for SaaS products is driving the growth of REST APIs in the FinTech sector, and Plaid is one of the top companies leading the charge toward “democratizing data” in financial services. This approach makes data accessible to everyone, regardless of technical ability, enabling the creation of custom experiences that meet users’ needs.

Final thoughts on REST APIs

In this article, you’ve gained an in-depth understanding of what a REST API is, how it works, what it’s used for, and more. You’ve also learned the difference between SOAP and REST. Learning about APIs can be challenging and daunting to new developers, but to help you keep growing and progressing in your career, Postman has crafted a new public REST API collection and API glossary, where you can expand your knowledge and understanding of a variety of REST APIs.

At Postman, we strive to make APIs more accessible and easy to work with. We want you to discover, play with, and find the value you’re looking for when it comes to putting API technology to work in your personal and professional world. Start growing, progressing and expanding your knowledge of REST APIs.

If you haven’t already downloaded the Postman app, you can get it for free here. Once you’ve downloaded Postman, go to this Public REST APIs collection page, click on the Run in Postman button for our public API collection, and you’ll immediately start to see how the applications you use every day rely on APIs to power the capabilities you depend on.