A REST API (Representational State Transfer Application Programming Interface) is a way for two computer systems to communicate over HTTP in a simple and uniform way. REST APIs provide a standardized way for different systems to exchange data without needing to know the details of each other’s implementation. At a high level, REST APIs can be used for:
Accessing and Manipulating Resources
The core idea behind REST is that entities/resources are exposed at endpoints, such as https://api.example.com/users/1234. REST APIs use HTTP requests to “GET”, “PUT”, “POST” and “DELETE” these resources. For example, to retrieve information about user 1234, you might issue a GET request to the users endpoint. To update information about that user, you would issue a PUT request to the same endpoint, containing the updated data. REST systems aim for resources to be easily accessible and modifiable using uniform interfaces.
Exposing Business Logic and Functionality
Beyond just accessing data, REST APIs allow services and platforms to expose business logic and functionality to other programs. For example, Stripe provides a REST API that enables developers to integrate payment processing into their own applications. Using Stripe’s API endpoints, an app can complete actions like charging credit cards and managing recurring billing. REST APIs provide a straightforward way to open up services and complex functionality to other systems over the internet.
Connecting Frontends and Backends
REST APIs are commonly used to connect user interfaces such as web and mobile applications to back-end systems and databases. The frontend app handles presentation and user interaction, while REST APIs provide a consistent interface to access data from the backend. This separation of concerns simplifies development and allows the frontend and backend to scale independently. For example, Facebook uses a REST API to enable its mobile apps and third-party developers to retrieve and post content to Facebook servers.
Enabling Integrations Between Systems
REST APIs enable different systems, even written in different languages and running on different platforms, to smoothly integrate with each other. Using REST APIs, two systems can communicate over HTTP in a standardized way without complex low-level protocols or proprietary interfaces. This simplifies integrations between new systems and legacy systems. For example, an e-commerce site could provide a REST API to allow other sites to retrieve product data in real time.
Creating Web Services
A REST API essentially provides web services that can be called over the internet. These web services allow organizations to open up business processes and capabilities to be invoked over HTTP. For example, the Twilio REST API enables developers to access telephony capabilities and send text messages from their own apps. Overall, exposing web services through REST APIs promotes reusability and modularity.
Developing API-First Services
With the proliferation of mobile apps and distributed systems, many organizations take an “API-first” approach to development. This involves designing APIs first, then using them to develop multiple platforms, rather than creating APIs as an afterthought. Developing APIs that properly encapsulate business capabilities enables greater agility and consistency across different apps and products.
Accessing REST APIs
There are a variety of ways to call REST APIs:
- Web apps can use AJAX requests to directly invoke REST endpoints.
- Mobile apps can call REST APIs to integrate backend data and services.
- Server-side programs can interact with REST APIs using HTTP client libraries.
- Command line tools like cURL provide an easy way to test REST APIs.
- Integrations can automatically sync data by polling REST API endpoints.
Overall, the simplicity of the REST model makes APIs accessible to virtually any client capable of HTTP networking.
REST API Best Practices
To leverage the full benefits of REST, APIs should follow constraints and architectural styles like:
- Statelessness – No client context is stored on the server between requests
- Cacheability – API responses should ideally be cacheable to improve performance
- Uniform interfaces – Resources should be manipulatable through predetermined interfaces
- Client-server separation – Client and server responsibilities should be separated
- Layered system – Components should be independently deployable
Other REST API best practices include:
- Consistent resource identification through URLs – e.g. /users/1234
- Use HTTP methods explicitly – GET, POST, PUT, DELETE
- Meaningful status codes and error handling
- Versioning to avoid breaking changes
- Thorough documentation
REST vs SOAP APIs
In contrast to REST, SOAP (Simple Object Access Protocol) APIs:
- Use a more rigid WSDL interface definition format
- Exchange complex XML documents rather than simple resources
- Use XML namespaces to provide envelope/header/body fields
- Can expose richer functionality through built-in features like WSDL and WS-Security
However, SOAP introduces more complexity with XML messaging rather than simple HTTP requests. In general, REST APIs are simpler, easier to implement across platforms, more scalable, and preferred for internet-based APIs exposed to diverse clients.
Popular REST APIs
Many popular web APIs use the REST model. Examples include:
- Twitter API – Enables posting tweets and accessing profile data
- Stripe API – Facilitates accepting payments
- Instagram API – Allows reading and writing photos and videos
- Facebook Graph API – Lets you read and modify Facebook data
- Twilio API – Provides voice, video, and messaging capabilities
Virtually every major web platform provides developer APIs and most use the REST paradigm for its simplicity, accessibility, and scalability.
REST API Security
There are several approaches for securing access to REST APIs including:
Basic Authentication
The client sends HTTP requests with an Authorization header containing base64 encoded user credentials (e.g. username:password). The server validates the credentials before providing access.
API Keys
Users pass a generated API key string in the request (often as a query param or header). The server checks the key against API keys stored in a database.
OAuth 2.0
For user-level authorization, OAuth 2.0 is a popular protocol where users grant access to REST APIs through a authorization server flow. Access tokens indicate specific authorized scopes.
JSON Web Tokens
JSON Web Tokens (JWT) are encoded JSON objects containing user identity and privileges that are cryptographically signed and passed in the request to the API. The server validates the signature to authenticate requests.
The Growth of REST APIs
REST APIs provide a simple yet powerful model for exposing services and data. Adoption has grown exponentially with the expansion of public and private APIs across industries. Advantages including loose coupling, internet scalability, and interoperability drive REST API popularity. As mobile and web systems continue to decentralize, REST APIs will remain a fundamental tool for integration.