Representational state transfer (REST) is an architectural style for designing distributed systems and web services. REST systems typically communicate over HTTP using methods like GET, PUT, POST and DELETE to manipulate resources through their uniform resource identifiers (URIs). Some key aspects of REST include:
Client-Server Architecture
REST systems have a separation between client and server. The server hosts the web services and data storage. The client requests information and services from the server. This helps modularize the concerns so server code can focus on core functionality while client code can focus on user interface and experience.
Statelessness
Client and server do not need to retain session state between requests. All the information required to process a request is contained within the request itself. The server does not need to retain client state between requests. This simplifies implementation and scaling of servers.
Caching
REST responses can include cache control headers to identify if and for how long data can be cached. This saves clients from having to make unnecessary repeat calls for the same information and can improve performance.
Uniform Interface
REST uses a uniform interface between components for communication. This typically means using HTTP requests with standard HTTP verbs like GET, POST, PUT, DELETE to manipulate resources through their URIs. This defines a consistent way for clients and servers to communicate.
Layered System
Client and server can be decomposed into hierarchical layers to improve modularity and encapsulation. A client for example may only interact with an API layer that hides lower level data storage details. This enables modifying underlying implementation details without impacting the client.
Code on Demand (Optional)
REST allows client functionality to be extended by downloading and executing code scripts. This allows clients to handle new data types without recompilation. However, this aspect is optional and not universally implemented.
Resource Identification through URIs
Every resource or object in a REST system should be uniquely identifiable and locatable through a consistent URI scheme. This enables locating, viewing and manipulating objects programmatically using standard HTTP verbs.
Manipulation through Representations
REST communication relies on passing resource representations back and forth. These representations encapsulate the current state of a resource and are rendered in standard formats like JSON, XML, HTML. Clients never directly interact with a resource itself.
Self Descriptive Messages
REST messages contain enough information for a component to process them independently, without relying on out-of-band information. REST requests include all details such as data format, authorization tokens, API version etc. to be understood independently.
Hypermedia as the Engine of Application State (HATEOAS)
REST responses contain not only data but links to transition the application to next desired state. The links denote possible application flows so clients only need to understand how to navigate REST links.
Common Examples of REST APIs
Some common examples of popular REST APIs on the web include:
Twitter REST API
The Twitter REST API allows accessing core Twitter data. APIs are provided to fetch tweets, user profiles, search tweets, post new tweets etc. The API uses HTTP methods like GET, POST, DELETE on Twitter resources identified by URIs.
GitHub REST API
The GitHub API allows managing GitHub resources like repositories, users, issues programmatically. APIs exist to create repositories, fork repos, open/close issues etc. HTTPS and JSON is used for all communication.
Stripe REST API
Stripe provides a REST API to integrate payment processing into an application. APIs allow creating charges, refunds, adding new customers etc. Communication uses HTTPS and JSON.
Google Maps REST APIs
Google Maps offers REST APIs to embed Google Maps, add markers, position cameras, add geometry overlays like paths, polygons etc. APIs use HTTPS and JSON.
Facebook Graph API
The Facebook Graph API allows reading and posting data to Facebook. It can fetch profiles, posts, photos and manipulate them. Communication uses HTTP/S with JSON.
Twilio REST API
Twilio provides a REST API to build voice, VoIP and messaging apps via the cloud. The API enables sending/receiving calls & texts, generating TwiML etc. over HTTPS.
Best Practices for Designing REST APIs
Some best practices to keep in mind when designing clean REST APIs:
- Use nouns over verbs in endpoint paths since REST focuses on resources
- Name collections with plural nouns
- Keep a consistent hierarchical structure for endpoints
- Use HTTP methods correctly – GET for read, PUT for replace, POST for create etc
- Use standard HTTP status codes for responses
- Authenticate via standard mechanisms like OAuth, Basic Auth, API Keys
- Version the APIs and maintain compatibility between versions
- Provide sufficient documentation and sample requests/responses
- Make responses self-descriptive including links, status info
- Make APIs explorable – clients should be able to discover API capabilities
Comparison of REST to SOAP Web Services
SOAP or Simple Object Access Protocol is another architectural approach to designing web services and APIs. Some key differences between REST and SOAP include:
| REST | SOAP |
|---|---|
| Uses lighter protocol based on REST principles over HTTPS | Uses XML-based messaging protocol over variety of transports like HTTP, SMTP etc |
| Emphasizes URIs for identifying resources and HTTP verbs for operating on them | Uses XML schema and WSDL contract to define service interface |
| Does not enforce use of a particular messaging format. JSON, XML, HTML can be used | Uses XML for all messaging |
| Designed for point-to-point client-server communication over HTTP | Supports sophisticated messaging patterns like asynchronous and broadcast messaging |
| Better suited for internet scale requirements due to lightweight nature | Heavier protocol so more complex for internet scale requirements |
| Loose coupling between client and server | Tight coupling between service provider and consumer |
| Stateless so no client context stored on server between requests | Can maintain session state |
| Caching helps enhance performance | Caching not built-in |
In summary, REST provides a simpler, lighter-weight alternative to SOAP which makes it a popular choice for APIs designed for internet scale usage by a wider variety of clients.
Challenges with REST APIs
Some challenges that can arise in working with REST APIs include:
- Versioning – maintaining compatibility across API versions
- Documentation – keeping detailed docs updated as APIs evolve
- Security – properly authenticating users and encrypting data
- Caching – balancing performance vs. freshness of data
- Error handling – sending correct status codes and info to clients
- Overfetching – clients fetching more data than required
- Chatty interfaces – requiring clients to make excessive requests
- Changing URIs – don’t break existing client integration
- Scale – designing for internet level loads
- Old browsers – supporting legacy clients with basic HTTP
These challenges can be mitigated through smart API design choices, tight client integration and continuous testing and monitoring of API usage in production.
Conclusion
REST has become the predominant architectural style for web APIs and services. Its constraints and principles encourage creating interfaces that focus on resources, leverage HTTP fully, and are easy to use and integrate with. REST combines a lightweight protocol with ubiquitous HTTP networking to provide an interoperable, internet-scale web services architecture.