Definition

RESTful API (REST API)

Contributor(s): Crystal Bedell; Ed Hannan; Sarah Wilson; Alexander Gillis

A RESTful API is an architectural style for an application program interface (API) that uses HTTP requests to access and use data. That data can be used to GET, PUT, POST and DELETE data types, which refers to the reading, updating, creating and deleting of operations concerning resources.

An API for a website is code that allows two software programs to communicate with each other. The API spells out the proper way for a developer to write a program requesting services from an operating system or other application.

A RESTful API -- also referred to as a RESTful web service or REST API -- is based on representational state transfer (REST), which is an architectural style and approach to communications often used in web services development.

REST technology is generally preferred over other similar technologies. This tends to be the case because REST uses less bandwidth, making it more suitable for efficient internet usage. RESTful APIs can also be built with programming languages such as JavaScript or Python.

The REST used by browsers can be thought of as the language of the internet. With cloud use on the rise, APIs are being used by cloud consumers to expose and organize access to web services. REST is a logical choice for building APIs that allow users to connect to, manage and interact with cloud services flexibly in a distributed environment. RESTful APIs are used by such sites as Amazon, Google, LinkedIn and Twitter.

How RESTful APIs work

A RESTful API breaks down a transaction to create a series of small modules. Each module addresses an underlying part of the transaction. This modularity provides developers with a lot of flexibility, but it can be challenging for developers to design their REST API from scratch. Currently, several companies provide models for developers to use; the models provided by Amazon S3, Cloud Data Management Interface (CDMI) and OpenStack Swift are the most popular.

A RESTful API uses commands to obtain resources. The state of a resource at any given timestamp is called a resource representation. A RESTful API uses existing HTTP methodologies defined by the RFC 2616 protocol, such as:

  • GET to retrieve a resource;
  • PUT to change the state of or update a resource, which can be an object, file or block;
  • POST to create that resource; and
  • DELETE to remove it.

With REST, networked components are a resource the user requests access to -- like a black box whose implementation details are unclear. All calls are stateless; nothing can be retained by the RESTful service between executions.

Data formats the REST API supports include:

  • application/json
  • application/xml
  • application/x-wbe+xml
  • application/x-www-form-urlencoded
  • multipart/form-data

Uses

Because the calls are stateless, REST is useful in cloud applications. Stateless components can be freely redeployed if something fails, and they can scale to accommodate load changes. This is because any request can be directed to any instance of a component; there can be nothing saved that has to be remembered by the next transaction. That makes REST preferable for web use. The RESTful model is also helpful in cloud services because binding to a service through an API is a matter of controlling how the URL is decoded. Cloud computing and microservices are almost certain to make RESTful API design the rule in the future.

RESTful API Design and Architecture Constraints

RESTful API design was defined by Dr. Roy Fielding in his 2000 doctorate dissertation. In order to be a true RESTful API, a web service must adhere to the following six REST architectural constraints:

  • Use of a uniform interface (UI). Resources should be uniquely identifiable through a single URL, and only by using the underlying methods of the network protocol, such as DELETE, PUT and GET with HTTP, should it be possible to manipulate a resource.
  • Client-server based. There should be a clear delineation between the client and server. UI and request-gathering concerns are the client's domain. Data access, workload management and security are the server's domain. This loose coupling of the client and server enables each to be developed and enhanced independent of the other.
  • Stateless operations. All client-server operations should be stateless, and any state management that is required should take place on the client, not the server.
  • RESTful resource caching. All resources should allow caching unless explicitly indicated that caching is not possible.
  • Layered system. REST allows for an architecture composed of multiple layers of servers.
  • Code on demand. Most of the time, a server will send back static representations of resources in the form of XML or JSON. However, when necessary, servers can send executable code to the client.

Common REST API challenges

Besides the design and architecture constraints, individuals will have to confront some challenges with REST APIs. Some concepts which may be challenging can include:

  • Endpoint consistency -- paths of endpoints should be consistent by following common web standards, which may be difficult to manage.
  • API versioning -- endpoint URLs shouldn't be invalidated when used internally or with other applications.
  • Long response times and too much data -- the amount of returned resources can increase in size in time, adding to increased load and response times.
  • Navigation paths and user input locations -- because REST uses URL paths for input parameters, determining URL spaces can be challenging.
  • Security -- which has a lot of aspects to keep an eye on, including the use of:
    • HTTPS;
    • blocking access from unknown IP addresses and domains;
    • validating URLs;
    • blocking unexpectedly large payloads;
    • logging requests; and
    • investigating failures.
  • Authentication -- use common authentication methods such as HTTP basic authentication (which allows for a base64-encoded username:password string), API keys, JSON Web Tokens and other access tokens. OAuth 2.0, for example, is good for access control.
  • Requests and data -- requests may have more data and metadata than needed or more requests may be needed to obtain all the data. APIs can be adjusted for this.
  • API testing -- can be a long process to set up and run. Each part of the process can be either long or challenging. Testing can also be done in the command line with the utility Curl. Parts of the testing process that may be challenging include:
    • Initial setup
    • Schema updates
    • Test parameter combinations
    • Sequence API calls
    • Validate test parameters
    • System integration
  • Define error codes and messages.
    • With error codes, it is more of a common practice to use standard HTTP error codes. These are recognized by clients and developers more often.
    • Error handling may not have a way to distinguish if a response is successful or not besides parsing the body or checking for an error.

REST vs. SOAP

REST and Simple Object Access Protocol (SOAP) offer different methods to invoke a web service. REST is an architectural style, while SOAP defines a standard communication protocol specification for XML-based message exchange. REST applications can use SOAP.

RESTful web services are stateless. A REST-based implementation is simple compared to SOAP, but users must understand the context and content being passed along, as there's no standard set of rules to describe the REST web services interface. REST services are useful for restricted profile devices, such as mobile, and are easy to integrate with existing websites.

SOAP requires less plumbing code -- meaning low-level, infrastructural code that connects main code modules together -- than REST services design. The Web Services Description Language describes a common set of rules to define the messages, bindings, operations and location of the service. SOAP web services are useful for asynchronous processing and invocation.

History of RESTful APIs

Prior to REST, developers used SOAP to integrate APIs. To make a call, developers handwrote an XML document with a Remote Procedure Call (RPC) in the body. They then specified the endpoint and POST their SOAP envelope to the endpoint.

In 2000, Roy Fielding and a group of developers decided to create a standard so that any server could talk to any other server. He defined REST and the architectural constraints explained above in his 2000 Ph.D. dissertation at the University of California, Irvine. These universal rules make it easier for developers to integrate software.

Salesforce was the first company to sell an API as part of its "Internet as a Service" package in 2000. However, few developers were actually able to use the complicated XML API. Then eBay built a REST API, which expanded its market to any site that could access its API. This caught the attention of another e-commerce giant, and Amazon announced its API in 2002.

Flickr launched its own RESTful API in August 2004, enabling bloggers to easily embed images on their sites and social media feeds. Facebook and Twitter both released their APIs in 2006, buckling under the pressure of developers who scraped the sites and created "Frankenstein" APIs. When Amazon Web Services (AWS) helped launch the cloud in 2006, developers were able to access data space in minutes using AWS's REST API, and the request for public APIs quickly escalated.

Since then, developers have embraced RESTful APIs, using them to add functionality to their websites and applications. Today, REST APIs are considered the "backbone of the internet."

This was last updated in September 2020

Continue Reading About RESTful API (REST API)

Dig Deeper on API management

Join the conversation

13 comments

Send me notifications when other members comment.

Please create a username to comment.

What will future RESTful API models look like and how will they differ from current designs?
Cancel
No one know the future. I wonder why people keep asking about the future and how will be the future of that or that? Did anyone traveler to the future and saw how will be?
Cancel
People ask about the future because they want to make decisions about what tools to use and what architecture to build, and deciding which will require the least amount of changes in the future. If you're building a house, would you build the foundation before deciding what size the house would be and how it would be used? This is a good question, and pfffff your answer shows you don't have a lot of experience with large application development. Web services has already changed significantly since it was first defined, and it will continue to do so.
Cancel
Love it!
Cancel
Every company in the world needs an API in the close future. There will be no way out in order to get connected.
Cancel
Hi,

What is REST API in layman's terms? Why REST API preferable for the IoT implementation?
Cancel
"REST technology is generally preferred to the more robust Simple Object Access Protocol (SOAP) technology because REST leverages less bandwidth"

It is highly debatable that SOAP is more robust than REST. Because SOAP is much more complicated it is more likely to be brittle and break.

The advantages of REST are much more than just "less bandwidth" which is just a technical non-functional aspect. REST just uses a few simple operators to provide all the functionality you need and this common way of working is understood across the web. Whereas, SOAP needs particular interfaces for each application and a lot of work to achieve anything.

REST also means systems are loosely coupled, whereas SOAP results in systems that are tightly coupled.

Thus the advantages of REST are also functional and logical.
Cancel
Wrong information. This article does not explain what is Restful API.
Cancel
Can we get data in my Android app through the API?
Cancel
Thank you for the article.

I am wondering whether you could please point me in the right direction about our issue with REST API?

We used to use a plugin called <a href="http://v2.wp-api.org/">REST API</a> that helped our Wordpress posts feed into an app.

But the plugin had to be deactivated because it stopped the new post editor in Wordpress 5.0.1 from working (would not Publish/Save, Featured image preview and Category and Tags tabs did not appear in editor).

Now, with the plugin deactivated, no new posts are able to be received/viewed in the app (but existing posts are OK).

What is the different between the plugin and what is now done natively in core and what can we do to get back the bits of the plugin than mace the post to app work?

I am not a coder so am very happy to freelance this out to someone to fix for us.
Cancel
what is API ?
Cancel
Here, check this out! 
https://searchmicroservices.techtarget.com/definition/application-program-interface-API
Cancel
Nice articles and very informative facts. No one produces these types of pieces of information.
https://www.revaalolabs.com/post/what-is-rest-api-a-comprehensive-guide-to-restful-apis
Cancel

SearchSoftwareQuality

SearchAWS

SearchCloudComputing

TheServerSide.com

Close