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.
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.
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:
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:
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.
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.
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.
Data within a response to a request must be labeled as cacheable or non-cacheable.
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.
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.
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:
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.
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:
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.
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.
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.
REST is preferable to SOAP for several reasons. Here are a few advantages that REST APIs have:
Along with design and architectural constraints, individuals will have to deal with some challenges when using REST APIs. These challenges may include:
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.
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.
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 provides authentication schemes for REST API implementation. Two common schemes are:
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 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.
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:
A response can contain more data than you need or require further requests to access all of the data.
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.
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:
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.
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.
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.
Provide comprehensive, easy-to-read API documentation that includes examples of requests and responses, authentication details, and error codes.
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.
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.
Now that you understand what a REST API is, let’s look at some examples:
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.
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.
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, Instagram offers a Graph API for professional accounts, enabling users to manage their online activities.
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.
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.
