What Is a REST API?
November 20, 2020

What Is a REST API?

API management

Spend any amount of time working with APIs, or reading API documentation, and you will certainly come across the term REST or RESTful API.

In this blog, we answer the question "What are REST APIs?", distinguish it from a similar architecture in a discussion of REST vs. SOAP, REST architecture constraints, and provide a RESTful API example.

What Is a REST API?

A REST (Representational State Transfer) API is an architectural style that uses HTTP to request access and use data.

The concept of REST was introduced in 2000 by Roy Fielding, a noted computer scientist who has influenced the development of many WWW standards. REST was, and remains, a core architectural principle for the web in general, and has gained traction as an alternative to WS* and SOAP-based web services for consumption within mobile devices, the "internet of things", and many open-web consumer-facing use cases.

For background information on APIs, check out our blog What Are APIs?

REST vs SOAP

SOAP (Simple Object Access Protocol) and REST serve similar purposes in architectural terms. Both enable software applications to call on web services to retrieve data or make procedure calls. SOAP and REST each have their advantages and drawbacks depending on use case.

SOAP is a protocol that uses Extensible Markup Language (XML) to transmit messages over a variety of transport protocols, including HTTP, TCP, IBM MQ (MOM), FTP, Java Message Service, and others. SOAP web services capabilities were built into most major software development tools. Opinions vary on the overall success but the consensus is that SOAP is a high degree of application integration at relatively low related standards. It has been adopted for security, policy management, message routing, and so forth, making SOAP enterprise-friendly.

In short, SOAP includes:

  • Independence of language, platform and transport. (In contrast, REST requires HTTP).
  • Works well in distributed environments, such as the enterprise. (REST assumes point-to-point).
  • Well-standardized after more than a decade of serious enterprise use.
  • Pre-build extensibility with WS* standards.
  • Built-in error handling.
  • Automation when used with certain languages.

REST works on top of the HTTP transport. It takes advantage of HTTP’s native capabilities, such as GET, PUT, POST and DELETE. When a request is sent to a RESTful API, the response (the “representation” of the information “resource” being sought) returns in either the JSON, XML or HTML format. A RESTful API is defined by a web address, or Uniform Resource Identifier (URI), which typically follows a naming convention.

In contrast to SOAP, REST is easier to work with and more flexible:

  • No expensive tools needed in order for interaction with web services.
  • Shorter learning curve.
  • More efficient (XML, used in SOAP messages, is longer than REST’s message formats).
  • Faster, with less processing required.

REST Architecture Constraints

A true RESTful API is defined by six architectural constraints which make any web service. They are:

Uniform Interface

The fundamental design to any RESTful system, which differentiates between a REST API and non-REST API. This constraint simplifies the architecture by providing a uniform way of interacting with a given server (irrespective of device or application type).

Client Server

This constraint essentially says that servers and clients should only know resource URIs, and that's all - there are no dependencies, and any can be developed and replaced independently so long as interface between them is unaltered. 

Statelessness

This constraint, by definition, means all client-server interactions are stateless. Every request is treated as new, with no sessions nor history. If the end-user requires a stateful application, then each request from the client then must contain all necessary information to service the request.

Cacheability

Caching in REST should be applied to resources when applicable . This can be implemented on both the server or client side. 

Layered System

REST enables using a layered system architecture, where perhaps the APIs are deployed on one server, data is stored on another, and requests are authenticated on yet another. 

Code on Demand

This optional constraint means that you are able to, upon need, provide executable code to the client.

REST API Example

As an example, imagine that MyWidgets.com, a fictional online store selling widgets, wanted to allow a mobile app to have access to its product catalog database.

It might create a RESTful API with a URI of http://api.mywidgets.com/ catalog. The mobile app developer could pull the catalog onto the app by writing an HTTP request of “GET” to this URI.

To get a specific item from the catalogue, the developer would write GET to a version of the api that contained the product number, such as the following: http://api. mysoles.com/catalog/[sku].

When the RESTful API received the HTTP request, it would return the product information in JSON or some other web standard format.

Final Thoughts

In this blog, you learned more about what REST APIs are and how they are used. We also examined the REST vs SOAP debate, described the constraints in REST API design, and provided a RESTful API example. We hope you have learned more about these types of APIs and how they can be used in your applications.

Additional Resources

Akana Sola's REST Designer makes it quick and easy to access any API in your portfolio using REST protocols. Learn more by clicking below.

Akana Sola

Want to see Akana in action? Click below to sign up for a free 30-day trial!

Try Free