What exactly is RESTful programming?
REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The key constraint is that the server and client must both agree on the media used, which in the case of the web is HTML.
An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. An HTML form is an example of this: The server specifies the location of the resource and the required fields. The browser doesn't know in advance where to submit the information, and it doesn't know in advance what information to submit. Both forms of information are entirely supplied by the server. (This principle is called HATEOAS: Hypermedia As The Engine Of Application State.)
So, how does this apply to HTTP, and how can it be implemented in practice? HTTP is oriented around verbs and resources. The two verbs in mainstream usage are GET and POST, which I think everyone will recognize. However, the HTTP standard defines several others such as PUT and DELETE. These verbs are then applied to resources, according to the instructions provided by the server.
For example, Let's imagine that we have a user database that is managed by a web service. Our service uses a custom hypermedia based on JSON, for which we assign the mimetype application/json+userdb (There might also be an application/xml+userdb and application/whatever+userdb - many media types may be supported). The client and the server have both been programmed to understand this format, but they don't know anything about each other. As Roy Fielding points out:
A REST API should spend almost all of its descriptive effort in
defining the media type(s) used for representing resources and driving
application state, or in defining extended relation names and/or
hypertext-enabled mark-up for existing standard media types.
A request for the base resource / might return something like this:
Request
GET /
Accept: application/json+userdb
Response
200 OK
Content-Type: application/json+userdb
{
"version": "1.0",
"links": [
{
"href": "/user",
"rel": "list",
"method": "GET"
},
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
We know from the description of our media that we can find information about related resources from sections called "links". This is called Hypermedia controls. In this case, we can tell from such a section that we can find a user list by making another request for /user:
Request
GET /user
Accept: application/json+userdb
Response
200 OK
Content-Type: application/json+userdb
{
"users": [
{
"id": 1,
"name": "Emil",
"country: "Sweden",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
{
"id": 2,
"name": "Adam",
"country: "Scotland",
"links": [
{
"href": "/user/2",
"rel": "self",
"method": "GET"
},
{
"href": "/user/2",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/2",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
We can tell a lot from this response. For instance, we now know we can create a new user by POSTing to /user:
Request
POST /user
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Karl",
"country": "Austria"
}
Response
201 Created
Content-Type: application/json+userdb
{
"user": {
"id": 3,
"name": "Karl",
"country": "Austria",
"links": [
{
"href": "/user/3",
"rel": "self",
"method": "GET"
},
{
"href": "/user/3",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/3",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
We also know that we can change existing data:
Request
PUT /user/1
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Emil",
"country": "Bhutan"
}
Response
200 OK
Content-Type: application/json+userdb
{
"user": {
"id": 1,
"name": "Emil",
"country": "Bhutan",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Notice that we are using different HTTP verbs (GET, PUT, POST, DELETE etc.) to manipulate these resources, and that the only knowledge we presume on the client's part is our media definition.
Further reading:
The many much better answers on this very page.
How I explained REST to my wife.
How I explained REST to my wife.
Martin Fowler's
thoughts
PayPal's API has hypermedia controls
(This answer has been the subject of a fair amount of criticism for missing the point. For the most part, that has been a fair critique. What I originally described was more in line with how REST was usually implemented a few years ago when I first wrote this, rather than its true meaning. I've revised the answer to better represent the real meaning.)
An architectural style called REST (Representational State Transfer) advocates that web applications should use HTTP as it was originally envisioned. Lookups should use GET requests. PUT, POST, and DELETE requests should be used for mutation, creation, and deletion respectively.
REST proponents tend to favor URLs, such as
http://myserver.com/catalog/item/1729
but the REST architecture does not require these "pretty URLs". A GET request with a parameter
http://myserver.com/catalog?item=1729
is every bit as RESTful.
Keep in mind that GET requests should never be used for updating information. For example, a GET request for adding an item to a cart
http://myserver.com/addToCart?cart=314159&item=1729
would not be appropriate. GET requests should be idempotent. That is, issuing a request twice should be no different from issuing it once. That's what makes the requests cacheable. An "add to cart" request is not idempotent—issuing it twice adds two copies of the item to the cart. A POST request is clearly appropriate in this context. Thus, even a RESTful web application needs its share of POST requests.
This is taken from the excellent book Core JavaServer faces book by David M. Geary.
RESTful programming is about:
resources being identified by a persistent identifier: URIs are the ubiquitous choice of identifier these days
resources being manipulated using a common set of verbs: HTTP methods are the commonly seen case - the venerable Create, Retrieve, Update, Delete becomes POST, GET, PUT, and DELETE. But REST is not limited to HTTP, it is just the most commonly used transport right now.
the actual representation retrieved for a resource is dependent on the request and not the identifier: use Accept headers to control whether you want XML, HTTP, or even a Java Object representing the resource
maintaining the state in the object and representing the state in the representation
representing the relationships between resources in the representation of the resource: the links between objects are embedded directly in the representation
resource representations describe how the representation can be used and under what circumstances it should be discarded/refetched in a consistent manner: usage of HTTP Cache-Control headers
The last one is probably the most important in terms of consequences and overall effectiveness of REST. Overall, most of the RESTful discussions seem to center on HTTP and its usage from a browser and what not. I understand that R. Fielding coined the term when he described the architecture and decisions that lead to HTTP. His thesis is more about the architecture and cache-ability of resources than it is about HTTP.
If you are really interested in what a RESTful architecture is and why it works, read his thesis a few times and read the whole thing not just Chapter 5! Next look into why DNS works. Read about the hierarchical organization of DNS and how referrals work. Then read and consider how DNS caching works. Finally, read the HTTP specifications (RFC2616 and RFC3040 in particular) and consider how and why the caching works the way that it does. Eventually, it will just click. The final revelation for me was when I saw the similarity between DNS and HTTP. After this, understanding why SOA and Message Passing Interfaces are scalable starts to click.
I think that the most important trick to understanding the architectural importance and performance implications of a RESTful and Shared Nothing architectures is to avoid getting hung up on the technology and implementation details. Concentrate on who owns resources, who is responsible for creating/maintaining them, etc. Then think about the representations, protocols, and technologies.
This is what it might look like.
Create a user with three properties:
POST /user
fname=John&lname=Doe&age=25
The server responds:
200 OK
Location: /user/123
In the future, you can then retrieve the user information:
GET /user/123
The server responds:
200 OK
<fname>John</fname><lname>Doe</lname><age>25</age>
To modify the record (lname and age will remain unchanged):
PATCH /user/123
fname=Johnny
To update the record (and consequently lname and age will be NULL):
PUT /user/123
fname=Johnny
A great book on REST is REST in Practice.
Must reads are Representational State Transfer (REST) and REST APIs must be hypertext-driven
See Martin Fowlers article the Richardson Maturity Model (RMM) for an explanation on what an RESTful service is.
To be RESTful a Service needs to fulfill the Hypermedia as the Engine of Application State. (HATEOAS), that is, it needs to reach level 3 in the RMM, read the article for details or the slides from the qcon talk.
The HATEOAS constraint is an acronym
for Hypermedia as the Engine of
Application State. This principle is
the key differentiator between a REST
and most other forms of client server
system.
...
A client of a RESTful application need
only know a single fixed URL to access
it. All future actions should be
discoverable dynamically from
hypermedia links included in the
representations of the resources that
are returned from that URL.
Standardized media types are also
expected to be understood by any
client that might use a RESTful API.
(From Wikipedia, the free encyclopedia)
REST Litmus Test for Web Frameworks is a similar maturity test for web frameworks.
Approaching pure REST: Learning to love HATEOAS is a good collection of links.
REST versus SOAP for the Public Cloud discusses the current levels of REST usage.
REST and versioning discusses Extensibility, Versioning, Evolvability, etc.
through Modifiability
What is REST?
REST stands for Representational State Transfer. (It is sometimes
spelled "ReST".) It relies on a stateless, client-server, cacheable
communications protocol -- and in virtually all cases, the HTTP
protocol is used.
REST is an architecture style for designing networked applications.
The idea is that, rather than using complex mechanisms such as CORBA,
RPC or SOAP to connect between machines, simple HTTP is used to make
calls between machines.
In many ways, the World Wide Web itself, based on HTTP, can be viewed
as a REST-based architecture. RESTful applications use HTTP requests
to post data (create and/or update), read data (e.g., make queries),
and delete data. Thus, REST uses HTTP for all four CRUD
(Create/Read/Update/Delete) operations.
REST is a lightweight alternative to mechanisms like RPC (Remote
Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will
see how much more simple REST is.
Despite being simple, REST is fully-featured; there's basically
nothing you can do in Web Services that can't be done with a RESTful
architecture. REST is not a "standard". There will never be a W3C
recommendataion for REST, for example. And while there are REST
programming frameworks, working with REST is so simple that you can
often "roll your own" with standard library features in languages like
Perl, Java, or C#.
One of the best reference I found when I try to find the simple real meaning of rest.
http://rest.elkstein.org/
REST is using the various HTTP methods (mainly GET/PUT/DELETE) to manipulate data.
Rather than using a specific URL to delete a method (say, /user/123/delete), you would send a DELETE request to the /user/[id] URL, to edit a user, to retrieve info on a user you send a GET request to /user/[id]
For example, instead a set of URLs which might look like some of the following..
GET /delete_user.x?id=123
GET /user/delete
GET /new_user.x
GET /user/new
GET /user?id=1
GET /user/id/1
You use the HTTP "verbs" and have..
GET /user/2
DELETE /user/2
PUT /user
It's programming where the architecture of your system fits the REST style laid out by Roy Fielding in his thesis. Since this is the architectural style that describes the web (more or less), lots of people are interested in it.
Bonus answer: No. Unless you're studying software architecture as an academic or designing web services, there's really no reason to have heard the term.
I would say RESTful programming would be about creating systems (API) that follow the REST architectural style.
I found this fantastic, short, and easy to understand tutorial about REST by Dr. M. Elkstein and quoting the essential part that would answer your question for the most part:
Learn REST: A Tutorial
REST is an architecture style for designing networked applications.
The idea is that, rather than using complex mechanisms such as CORBA,
RPC or SOAP to connect between machines, simple HTTP is used to make
calls between machines.
In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture.
RESTful applications use HTTP requests to post data (create and/or
update), read data (e.g., make queries), and delete data. Thus, REST
uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.
I don't think you should feel stupid for not hearing about REST outside Stack Overflow..., I would be in the same situation!; answers to this other SO question on Why is REST getting big now could ease some feelings.
I apologize if I'm not answering the question directly, but it's easier to understand all this with more detailed examples. Fielding is not easy to understand due to all the abstraction and terminology.
There's a fairly good example here:
Explaining REST and Hypertext: Spam-E the Spam Cleaning Robot
And even better, there's a clean explanation with simple examples here (the powerpoint is more comprehensive, but you can get most of it in the html version):
http://www.xfront.com/REST.ppt or http://www.xfront.com/REST.html
After reading the examples, I could see why Ken is saying that REST is hypertext-driven. I'm not actually sure that he's right though, because that /user/123 is a URI that points to a resource, and it's not clear to me that it's unRESTful just because the client knows about it "out-of-band."
That xfront document explains the difference between REST and SOAP, and this is really helpful too. When Fielding says, "That is RPC. It screams RPC.", it's clear that RPC is not RESTful, so it's useful to see the exact reasons for this. (SOAP is a type of RPC.)
What is REST?
REST in official words, REST is an architectural style built on certain principles using the current “Web” fundamentals.
There are 5 basic fundamentals of web which are leveraged to create REST services.
Principle 1: Everything is a Resource
In the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs), typically links on the Web.
Principle 2: Every Resource is Identified by a Unique Identifier (URI)
Principle 3: Use Simple and Uniform Interfaces
Principle 4: Communication is Done by Representation
Principle 5: Be Stateless
I see a bunch of answers that say putting everything about user 123 at resource "/user/123" is RESTful.
Roy Fielding, who coined the term, says REST APIs must be hypertext-driven. In particular, "A REST API must not define fixed resource names or hierarchies".
So if your "/user/123" path is hardcoded on the client, it's not really RESTful. A good use of HTTP, maybe, maybe not. But not RESTful. It has to come from hypertext.
The answer is very simple, there is a dissertation written by Roy Fielding.]1 In that dissertation he defines the REST principles. If an application fulfills all of those principles, then that is a REST application.
The term RESTful was created because ppl exhausted the word REST by calling their non-REST application as REST. After that the term RESTful was exhausted as well. Nowadays we are talking about Web APIs and Hypermedia APIs, because the most of the so called REST applications did not fulfill the HATEOAS part of the uniform interface constraint.
The REST constraints are the following:
client-server architecture
So it does not work with for example PUB/SUB sockets, it is based on REQ/REP.
stateless communication
So the server does not maintain the states of the clients. This means that you cannot use server a side session storage and you have to authenticate every request. Your clients possibly send basic auth headers through an encrypted connection. (By large applications it is hard to maintain many sessions.)
usage of cache if you can
So you don't have to serve the same requests again and again.
uniform interface as common contract between client and server
The contract between the client and the server is not maintained by the server. In other words the client must be decoupled from the implementation of the service. You can reach this state by using standard solutions, like the IRI (URI) standard to identify resources, the HTTP standard to exchange messages, standard MIME types to describe the body serialization format, metadata (possibly RDF vocabs, microformats, etc.) to describe the semantics of different parts of the message body. To decouple the IRI structure from the client, you have to send hyperlinks to the clients in hypermedia formats like (HTML, JSON-LD, HAL, etc.). So a client can use the metadata (possibly link relations, RDF vocabs) assigned to the hyperlinks to navigate the state machine of the application through the proper state transitions in order to achieve its current goal.
For example when a client wants to send an order to a webshop, then it have to check the hyperlinks in the responses sent by the webshop. By checking the links it founds one described with the http://schema.org/OrderAction. The client know the schema.org vocab, so it understands that by activating this hyperlink it will send the order. So it activates the hyperlink and sends a POST https://example.com/api/v1/order message with the proper body. After that the service processes the message and responds with the result having the proper HTTP status header, for example 201 - created by success. To annotate messages with detailed metadata the standard solution to use an RDF format, for example JSON-LD with a REST vocab, for example Hydra and domain specific vocabs like schema.org or any other linked data vocab and maybe a custom application specific vocab if needed. Now this is not easy, that's why most ppl use HAL and other simple formats which usually provide only a REST vocab, but no linked data support.
build a layered system to increase scalability
The REST system is composed of hierarchical layers. Each layer contains components which use the services of components which are in the next layer below. So you can add new layers and components effortless.
For example there is a client layer which contains the clients and below that there is a service layer which contains a single service. Now you can add a client side cache between them. After that you can add another service instance and a load balancer, and so on... The client code and the service code won't change.
code on demand to extend client functionality
This constraint is optional. For example you can send a parser for a specific media type to the client, and so on... In order to do this you might need a standard plugin loader system in the client, or your client will be coupled to the plugin loader solution.
REST constraints result a highly scalable system in where the clients are decoupled from the implementations of the services. So the clients can be reusable, general just like the browsers on the web. The clients and the services share the same standards and vocabs, so they can understand each other despite the fact that the client does not know the implementation details of the service. This makes possible to create automated clients which can find and utilize REST services to achieve their goals. In long term these clients can communicate to each other and trust each other with tasks, just like humans do. If we add learning patterns to such clients, then the result will be one or more AI using the web of machines instead of a single server park. So at the end the dream of Berners Lee: the semantic web and the artificial intelligence will be reality. So in 2030 we end up terminated by the Skynet. Until then ... ;-)
RESTful (Representational state transfer) API programming is writing web applications in any programming language by following 5 basic software architectural style principles:
Resource (data, information).
Unique global identifier (all resources are unique identified by URI).
Uniform interface - use simple and standard interface (HTTP).
Representation - all communication is done by representation (e.g. XML/JSON)
Stateless (every request happens in complete isolation, it's easier to cache and load-balance),
In other words you're writing simple point-to-point network applications over HTTP which uses verbs such as GET, POST, PUT or DELETE by implementing RESTful architecture which proposes standardization of the interface each “resource” exposes. It is nothing that using current features of the web in a simple and effective way (highly successful, proven and distributed architecture). It is an alternative to more complex mechanisms like SOAP, CORBA and RPC.
RESTful programming conforms to Web architecture design and, if properly implemented, it allows you to take the full advantage of scalable Web infrastructure.
Here is my basic outline of REST. I tried to demonstrate the thinking behind each of the components in a RESTful architecture so that understanding the concept is more intuitive. Hopefully this helps demystify REST for some people!
REST (Representational State Transfer) is a design architecture that outlines how networked resources (i.e. nodes that share information) are designed and addressed. In general, a RESTful architecture makes it so that the client (the requesting machine) and the server (the responding machine) can request to read, write, and update data without the client having to know how the server operates and the server can pass it back without needing to know anything about the client. Okay, cool...but how do we do this in practice?
The most obvious requirement is that there needs to be a universal language of some sort so that the server can tell the client what it is trying to do with the request and for the server to respond.
But to find any given resource and then tell the client where that resource lives, there needs to be a universal way of pointing at resources. This is where Universal Resource Identifiers (URIs) come in; they are basically unique addresses to find the resources.
But the REST architecture doesn’t end there! While the above fulfills the basic needs of what we want, we also want to have an architecture that supports high volume traffic since any given server usually handles responses from a number of clients. Thus, we don’t want to overwhelm the server by having it remember information about previous requests.
Therefore, we impose the restriction that each request-response pair between the client and the server is independent, meaning that the server doesn’t have to remember anything about previous requests (previous states of the client-server interaction) to respond to a new request. This means that we want our interactions to be stateless.
To further ease the strain on our server from redoing computations that have already been recently done for a given client, REST also allows caching. Basically, caching means to take a snapshot of the initial response provided to the client. If the client makes the same request again, the server can provide the client with the snapshot rather than redo all of the computations that were necessary to create the initial response. However, since it is a snapshot, if the snapshot has not expired--the server sets an expiration time in advance--and the response has been updated since the initial cache (i.e. the request would give a different answer than the cached response), the client will not see the updates until the cache expires (or the cache is cleared) and the response is rendered from scratch again.
The last thing that you’ll often here about RESTful architectures is that they are layered. We have actually already been implicitly discussing this requirement in our discussion of the interaction between the client and server. Basically, this means that each layer in our system interacts only with adjacent layers. So in our discussion, the client layer interacts with our server layer (and vice versa), but there might be other server layers that help the primary server process a request that the client does not directly communicate with. Rather, the server passes on the request as necessary.
Now, if all of this sounds familiar, then great. The Hypertext Transfer Protocol (HTTP), which defines the communication protocol via the World Wide Web is an implementation of the abstract notion of RESTful architecture (or an implementation of the abstract REST class if you're an OOP fanatic like me). In this implementation of REST, the client and server interact via GET, POST, PUT, DELETE, etc., which are part of the universal language and the resources can be pointed to using URLs.
If I had to reduce the original dissertation on REST to just 3 short sentences, I think the following captures its essence:
Resources are requested via URLs.
Protocols are limited to what you can communicate by using URLs.
Metadata is passed as name-value pairs (post data and query string parameters).
After that, it's easy to fall into debates about adaptations, coding conventions, and best practices.
Interestingly, there is no mention of HTTP POST, GET, DELETE, or PUT operations in the dissertation. That must be someone's later interpretation of a "best practice" for a "uniform interface".
When it comes to web services, it seems that we need some way of distinguishing WSDL and SOAP based architectures which add considerable overhead and arguably much unnecessary complexity to the interface. They also require additional frameworks and developer tools in order to implement. I'm not sure if REST is the best term to distinguish between common-sense interfaces and overly engineered interfaces such as WSDL and SOAP. But we need something.
REST is an architectural pattern and style of writing distributed applications. It is not a programming style in the narrow sense.
Saying you use the REST style is similar to saying that you built a house in a particular style: for example Tudor or Victorian. Both REST as an software style and Tudor or Victorian as a home style can be defined by the qualities and constraints that make them up. For example REST must have Client Server separation where messages are self-describing. Tudor style homes have Overlapping gables and Roofs that are steeply pitched with front facing gables. You can read Roy's dissertation to learn more about the constraints and qualities that make up REST.
REST unlike home styles has had a tough time being consistently and practically applied. This may have been intentional. Leaving its actual implementation up to the designer. So you are free to do what you want so as long as you meet the constraints set out in the dissertation you are creating REST Systems.
Bonus:
The entire web is based on REST (or REST was based on the web). Therefore as a web developer you might want aware of that although it's not necessary to write good web apps.
I think the point of restful is the separation of the statefulness into a higher layer while making use of the internet (protocol) as a stateless transport layer. Most other approaches mix things up.
It's been the best practical approach to handle the fundamental changes of programming in internet era. Regarding the fundamental changes, Erik Meijer has a discussion on show here: http://www.infoq.com/interviews/erik-meijer-programming-language-design-effects-purity#view_93197 . He summarizes it as the five effects, and presents a solution by designing the solution into a programming language. The solution, could also be achieved in the platform or system level, regardless of the language. The restful could be seen as one of the solutions that has been very successful in the current practice.
With restful style, you get and manipulate the state of the application across an unreliable internet. If it fails the current operation to get the correct and current state, it needs the zero-validation principal to help the application to continue. If it fails to manipulate the state, it usually uses multiple stages of confirmation to keep things correct. In this sense, rest is not itself a whole solution, it needs the functions in other part of the web application stack to support its working.
Given this view point, the rest style is not really tied to internet or web application. It's a fundamental solution to many of the programming situations. It is not simple either, it just makes the interface really simple, and copes with other technologies amazingly well.
Just my 2c.
Edit: Two more important aspects:
Statelessness is misleading. It is about the restful API, not the application or system. The system needs to be stateful. Restful design is about designing a stateful system based on a stateless API. Some quotes from another QA:
REST, operates on resource representations, each one identified by an URL. These are typically not data objects, but complex objects abstractions.
REST stands for "representational state transfer", which means it's all about communicating and modifying the state of some resource in a system.
Idempotence: An often-overlooked part of REST is the idempotency of most verbs. That leads to robust systems and less interdependency of exact interpretations of the semantics.
REST defines 6 architectural constraints which make any web service – a true RESTful API.
Uniform interface
Client–server
Stateless
Cacheable
Layered system
Code on demand (optional)
https://restfulapi.net/rest-architectural-constraints/
Old question, newish way of answering. There's a lot of misconception out there about this concept. I always try to remember:
Structured URLs and Http Methods/Verbs are not the definition of
restful programming.
JSON is not restful programming
RESTful programming is not for APIs
I define restful programming as
An application is restful if it provides resources (being the combination of data + state transitions controls) in a media type the client understands
To be a restful programmer you must be trying to build applications that allow actors to do things. Not just exposing the database.
State transition controls only make sense if the client and server agree upon a media type representation of the resource. Otherwise there's no way to know what's a control and what isn't and how to execute a control. IE if browsers didn't know <form> tags in html then there'd be nothing for you to submit to transition state in your browser.
I'm not looking to self promote, but i expand on these ideas to great depth in my talk http://techblog.bodybuilding.com/2016/01/video-what-is-restful-200.html .
An excerpt from my talk is about the often referred to richardson maturity model, i don't believe in the levels, you either are RESTful (level 3) or you are not, but what i like to call out about it is what each level does for you on your way to RESTful
This is amazingly long "discussion" and yet quite confusing to say the least.
IMO:
1) There is no such a thing as restful programing, without a big joint and lots of beer :)
2) Representational State Transfer (REST) is an architectural style specified in the dissertation of Roy Fielding.
It has a number of constraints. If your Service/Client respect those then it is RESTful. This is it.
You can summarize(significantly) the constraints to :
stateless communication
respect HTTP specs (if HTTP is used)
clearly communicates the content formats transmitted
use hypermedia as the engine of application state
There is another very good post which explains things nicely.
A lot of answers copy/pasted valid information mixing it and adding some confusion. People talk here about levels, about RESTFul URIs(there is not such a thing!), apply HTTP methods GET,POST,PUT ... REST is not about that or not only about that.
For example links - it is nice to have a beautifully looking API but at the end the client/server does not really care of the links you get/send it is the content that matters.
In the end any RESTful client should be able to consume to any RESTful service as long as the content format is known.
This answer is for absolute beginners, let's know about most used API architecture today.
To understand Restful programming or Restful API. First, you have to understand what API is, on a very high-level API stands for Application Programming Interface, it's basically a piece of software that can be used by another piece of software in order to allow applications to talk to each other.
The most widely used type of API in the globe is web APIs while an app that sends data to a client whenever a request comes in.
In fact, APIs aren't only used to send data and aren't always related to web development or javascript or python or any programming language or framework.
The application in API can actually mean many different things as long as the pice of software is relatively stand-alone. Take for example, the File System or the HTTP Modules we can say that they are small pieces of software and we can use them, we can interact with them by using their API. For example when we use the read file function for a file system module of any programming language, we are actually using the file_system_reading API. Or when we do DOM manipulation in the browser, we're are not really using the JavaScript language itself, but rather, the DOM API that browser exposes to us, so it gives us access to it. Or even another example let's say we create a class in any programming language like Java and then add some public methods or properties to it, these methods will then be the API of each object created from that class because we are giving other pieces of software the possibility of interacting with our initial piece of software, the objects in this case. S0, API has actually a broader meaning than just building web APIs.
Now let's take a look at the REST Architecture to build APIs.
REST which stands for Representational State Transfer is basically a way of building web APIs in a logical way, making them easy to consume for ourselves or for others.
To build Restful APIs following the REST Architecture, we just need to follow a couple of principles.
1. We need to separate our API into logical resources.
2. These resources should then be exposed by using resource-based URLs.
3. To perform different actions on data like reading, creating, or deleting data the API should use the right HTTP methods and not the URL.
4. Now the data that we actually send back to the client or that we received from the client should usually use the JSON data format, were some formatting standard applied to it.
5. Finally, another important principle of EST APIs is that they must be stateless.
Separate APIs into logical resources: The key abstraction of information in REST is a resource, and therefore all the data that we wanna share in the API should be divided into logical resources. What actually is a resource? Well, in the context of REST it is an object or a representation of something which has some data associated to it. For example, applications like tour-guide tours, or users, places, or revies are of the example of logical resources. So basically any information that can be named can be a resource. Just has to name, though, not a verb.
Expose Structure: Now we need to expose, which means to make available, the data using some structured URLs, that the client can send a request to. For example something like this entire address is called the URL. and this / addNewTour is called and API Endpoint.
Our API will have many different endpoints just like bellow
https://www.tourguide.com/addNewTour
https://www.tourguide.com/getTour
https://www.tourguide.com/updateTour
https://www.tourguide.com/deleteTour
https://www.tourguide.com/getRoursByUser
https://www.tourguide.com/deleteToursByUser
Each of these API will send different data back to the client on also perform different actions.
Now there is something very wrong with these endpoints here because they really don't follow the third rule which says that we should only use the HTTP methods in order to perform actions on data. So endpoints should only contain our resources and not the actions that we are performed on them because they will quickly become a nightmare to maintain.
How should we use these HTTP methods in practice? Well let's see how these endpoints should actually look like starting with /getTour. So this getTour endpoint is to get data about a tour and so we should simply name the endpoint /tours and send the data whenever a get request is made to this endpoint. So in other words, when a client uses a GET HTTP method to access the endpoint,
(we only have resources in the endpoint or in the URL and no verbs because the verb is now in the HTTP method, right?
The common practice to always use the resource name in the plural which is why I wrote /tours nor /tour.)
The convention is that when calling endpoint /tours will get back all the tours that are in a database, but if we only want the tour with one ID, let's say seven, we add that seven after another slash(/tours/7) or in a search query (/tours?id=7), And of course, it could also be the name of a tour instead of the ID.
HTTP Methods: What's really important here is how the endpoint name is the exact same name for all.
GET: (for requesting data from the server.)
https://www.tourguide.com/tours/7
POST: (for sending data to the server.)
https://www.tourguide.com/tours
PUT/PATCH: (for updating requests for data to the server.) https://www.tourguide.com/tours/7
DELETE: (for deleting request for data to the server.)
https://www.tourguide.com/tours/7
The difference between PUT and PATCH->
By using PUT, the client is supposed to send the entire updated object, while with PATCH it is supposed to send only the part of the object that has been changed.
By using HTTP methods users can perform basic four CRUD operations, CRUD stands for Create, Read, Update, and Delete.
Now there could be a situation like a bellow:
So, /getToursByUser can simply be translated to /users/tours, for user number 3 end point will be like /users/3/tours.
if we want to delete a particular tour of a particular user then the URL should be like /users/3/tours/7, here user id:3 and tour id: 7.
So there really are tons of possibilities of combining resources like this.
Send data as JSON: Now about data that the client actually receives, or that the server receives from the client, usually we use the JSON Data Format.
A typical JSON might look like below:
Before sending JSON Data we usually do some simple response formatting, there are a couple of standards for this, but one of the very simple ones called Jsend. We simply create a new object, then add a status message to it in order to inform the client whether the request was a success, fail, or error. And then we put our original data into a new object called Data.
Wrapping the data into an additional object like we did here is called Enveloping, and it's a common practice to mitigate some security issues and other problems.
Restful API should always be stateless: Finally a RESTful API should always be stateless meaning that, in a stateless RESTful API all state is handled on the client side no on the server. And state simply refers to a piece of data in the application that might change over time. For example, whether a certain user is logged in or on a page with a list with several pages what the current page is?
Now the fact that the state should be handled on the client means that each request must contain all the information that is necessary to process a certain request on the server. So the server should never ever have to remember the previous request in order to process the current request.
Let's say that currently we are on page five and we want to move forward to page six. Sow we could have a simple endpoint called /tours/nextPage and submit a request to server, but the server would then have to figure out what the current page is, and based on that server will send the next page to the client. In other words, the server would have to remember the previous request. This is what exactly we want to avoid in RESTful APIs.
Instead of this case, we should create a /tours/page endpoint
and paste the number six to it in order to request page number six /tours/page/6 . So the server doesn't have to remember anything in, all it has to do is to send back data for page number six as we requested.
Statelessness and Statefulness which is the opposite are very important concepts in computer science and applications in general
REST === HTTP analogy is not correct until you do not stress to the fact that it "MUST" be HATEOAS driven.
Roy himself cleared it here.
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand).
[Failure here implies that out-of-band information is driving interaction instead of hypertext.]
REST stands for Representational state transfer.
It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used.
REST is often used in mobile applications, social networking Web sites, mashup tools and automated business processes. The REST style emphasizes that interactions between clients and services is enhanced by having a limited number of operations (verbs). Flexibility is provided by assigning resources (nouns) their own unique universal resource indicators (URIs).
Introduction about Rest
Talking is more than simply exchanging information. A Protocol is actually designed so that no talking has to occur. Each party knows what their particular job is because it is specified in the protocol. Protocols allow for pure information exchange at the expense of having any changes in the possible actions. Talking, on the other hand, allows for one party to ask what further actions can be taken from the other party. They can even ask the same question twice and get two different answers, since the State of the other party may have changed in the interim. Talking is RESTful architecture. Fielding's thesis specifies the architecture that one would have to follow if one wanted to allow machines to talk to one another rather than simply communicate.
There is not such notion as "RESTful programming" per se. It would be better called RESTful paradigm or even better RESTful architecture. It is not a programming language. It is a paradigm.
From Wikipedia:
In computing, representational state transfer (REST) is an
architectural style used for web development.
The point of rest is that if we agree to use a common language for basic operations (the http verbs), the infrastructure can be configured to understand them and optimize them properly, for example, by making use of caching headers to implement caching at all levels.
With a properly implemented restful GET operation, it shouldn't matter if the information comes from your server's DB, your server's memcache, a CDN, a proxy's cache, your browser's cache or your browser's local storage. The fasted, most readily available up to date source can be used.
Saying that Rest is just a syntactic change from using GET requests with an action parameter to using the available http verbs makes it look like it has no benefits and is purely cosmetic. The point is to use a language that can be understood and optimized by every part of the chain. If your GET operation has an action with side effects, you have to skip all HTTP caching or you'll end up with inconsistent results.
This is very less mentioned everywhere but the Richardson's Maturity Model is one of the best methods to actually judge how Restful is one's API. More about it here:
Richardson's Maturity Model
What is API Testing?
API testing utilizes programming to send calls to the API and get the yield. It testing regards the segment under test as a black box. The objective of API testing is to confirm right execution and blunder treatment of the part preceding its coordination into an application.
REST API
REST: Representational State Transfer.
It’s an arrangement of functions on which the testers performs requests and receive responses. In REST API interactions are made via HTTP protocol.
REST also permits communication between computers with each other over a network.
For sending and receiving messages, it involves using HTTP methods, and it does not require a strict message definition, unlike Web services.
REST messages often accepts the form either in form of XML, or JavaScript Object Notation (JSON).
4 Commonly Used API Methods:-
GET: – It provides read only access to a resource.
POST: – It is used to create or update a new resource.
PUT: – It is used to update or replace an existing resource or create a new resource.
DELETE: – It is used to remove a resource.
Steps to Test API Manually:-
To use API manually, we can use browser based REST API plugins.
Install POSTMAN(Chrome) / REST(Firefox) plugin
Enter the API URL
Select the REST method
Select content-Header
Enter Request JSON (POST)
Click on send
It will return output response
Steps to Automate REST API
I would say that an important building block in understanding REST lies in the endpoints or mappings, such as /customers/{id}/balance.
You can imagine such an endpoint as being the connecting pipeline from the website (front-end) to your database/server (back-end). Using them, the front-end can perform back-end operations which are defined in the corresponding methods of any REST mapping in your application.
Related
I have a Soap service that is running over http. Is this also a REST service. What are the criteria that would make it a REST service. What are the criteria that would definitively exclude it as a REST service? There are posts (e.g. here) that compare REST and Soap but do not seem to answer this question directly. My answer is: Yes, a Soap service at its functional level is an http request that returns an XML payload where state is not maintained by the server and is therefore a REST service.
Fielding stated in his dissertation:
REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.
If you compare the above mentioned properties with Web-browsing, you will find plenty of similarities between both as Fielding just took the concepts which made the Web such a success and applied it onto a more general field, that also should allow applications to "surf the Web".
In order to rightfully call an architecture REST it has to support self-descriptiveness, scalability and cacheability while also respecting and adhering to the rules and semantics outlined by the underlying transport protocol and enforce the usage of well-defined standards, such as media types, link relation names, HTTP operations, URI standards, ...
Self-descriptiveness of a service is utilized by HATEOAS (or hate-us, as I tend to pronounce it, as people like me who see the benefit in REST always have to stress this key-term, which therefore also ended up in its own meme). Via HATEOAS a client is served by the server with all the available "actions" a client could take from the current "state" the client is in. An "action" here is just a link with an accompanying link-relation name a client can use to deduce when to best invoke that URI. The media-type the response was returned for may define what to do with such links. HTML i.e. states that on clicking a link a GET request is triggered and the content of the link is loaded either in the current pane or in a new tab, depending on the arguments the link has. Other media-types may defines something similar or something different at all. The general motto here, though, is: proceeding thru exploring. The interaction model in a REST architecture is therefore best designed as affordance and state machine while the actual service should follow more like a Web site approach where a server is teaching a client, i.e. on how a request has to look like and where to send the request to (similar to HTML forms).
As plenty of Web pages are more or less static and a majority of requests are retrieval focused, the Web heavily relies on caching. The same is generally expected from REST APIs as well, hence the strong requirement for cacheability here, as this could reduce the workload on servers quite notably if proper caching is in place.
By keeping client state away from servers this also allows to add new copies of a service onto new servers located behind a load balancer or new regions and thus increase scalability. A client usually does not care where it retrieves the data from, hence a server might just return a URI pointing to a clone instead of itself.
SOAP on the other hand is RPC, like Java's remote method invocation (RMI) or CORBA, where you have an own interface definition language (IDL) to generate client side stub-code for you, that contains the actual logic on how to transform certain objects into byte streams and how to send them over the wire, where you invoke certain methods.
Where SOAP violates REST constraints is clearly by the lack of caching support as well as out-of-band knowledge that needs to be available before actually using a client. SOAP messages are usually always exchanged as POST operations, which are not cacheable by default. Certain HTTP headers are available to allow intermediary servers to cache the response though SOAP doesn't make use of such and thus lacks general support for it.
A client developed for SOAP endpoint A will most likely also not be interoperable with a further SOAP endpoint B ran by a different company. While one might argue that a Web client also does not know how to process each of the different media-types, browsers usually provide plugin mechanism to load that kind of knowledge into the client. A media type is in addition to that also standardized, at least it should be, and may therefore be usable with plenty of servers (think of Flash-support i.e.). A further problem SOAP services have is, that once anything is changed in the WSDL definition clients not aware of the update will most likely stop to work with that updated service until the client code is updated to work with the latest version of the generated stub classes.
In regards to the XML format exchanged in SOAP: While technically it is doable for a REST service to return a SOAP XML payload, the format itself lacks support of HATEOAS, which is a necessity and not an option. How should a client make further choices based on the received response simply on the content received without any a-priori knowledge of the API itself?
I hope you can see that SOAP lacks support of caching, may have problems with scalability as well as leads to a tight coupling of clients to the actual API. The lack of HATEOAS support by the SOAP message envelop/header/body also does not allow clients to explore the API freely and thus adapt to server changes automatically.
Proper REST services follow the architectural guidelines spelled out in chapter five of Roy Fielding's dissertation. Most people erroneously use the term "REST API" when they really mean "HTTP API". Statelessness is a necessary but not sufficient condition for an API to adhere to the REST architectural guidelines.
I want to know the main difference between REST and API. Sometimes I see REST API in programming documents, then is REST or API same as REST API? I would like to know more about relation between REST, API and REST API.
REST is a type of API. Not all APIs are REST, but all REST services are APIs.
API is a very broad term. Generally it's how one piece of code talks to another. In web development API often refers to the way in which we retrieve information from an online service. The API documentation will give you a list of URLs, query parameters and other information on how to make a request from the API, and inform you what sort of response will be given for each query.
REST is a set of rules/standards/guidelines for how to build a web API. Since there are many ways to do so, having an agreed upon system of structuring an API saves time in making decisions when building one, and saves time in understanding how to use one.
Other popular API paradigms include SOAP and GraphQL.
Note that the above attempts to answer the question in regards to how the terms are commonly used in web development. Roman Vottner has offered a different answer below which offers good insights into the original definition of the term REST with more technical precision than I have provided here.
REST mostly just refers to using the HTTP protocol the way it was intended. Use the GET HTTP method on a URL to retrieve information, possibly in different formats based on HTTP Accept headers. Use the POST HTTP method to create new items on the server, PUT to edit existing items, DELETE to delete them. Make the API idempotent, i.e. repeating the same query with the same information should yield the same result. Structure your URLs in a hierarchical manner etc.
REST just is a guiding principle how to use URLs and the HTTP protocol to structure an API. It says nothing about return formats, which may just as well be JSON.
That is opposed to, for example, APIs that send binary or XML messages to a designated port, not using differences in HTTP methods or URLs at all.
There is no comparison in REST and API, REST is an API type.
API, in general, is a set of protocols deployed over an application software to communicate with other software components (Like browser interacting with servers) and provide an interface to services which the application software
offers to several live consumers.
And Rest is a form of principle which an API follows in which the server provides information whatever the client desires to interact with services.
REST basically is a style of web architecture that governs the behavior of clients and servers. While API is a more general set of protocols and is deployed over the software to help it interact with some other software.
REST is only geared towards web applications. And mostly deals with HTTP requests and responses. This makes it practically usable by any programming language and easy to test.
API is an acronym for Application Programming Interface and defines a set of structures (i.e. classes) one has to implement in order to interact with a service the API was exposed for. APIs usually expose operations that can be invoked including any required or supported arguments as well as the expected responses. Classical examples here are Corba IDL, SOAP or RMI in the Java ecosystem but also RPC-like usages of Web systems specified in documentation like Swagger or OpenAPI.
REST (REpresentational State Transfer) on the contrary was specified by Fielding in his doctoral thesis where he analyzed how the whole user interactions occurs on the Web. He realized that on the Web only a transport protocol, a naming scheme for stuff as well as a well defined exchanged format is needed to exchange messages or documents. These three parts therefore define the interface to interact with peers in such a ecosystem. The transport layer is covered by HTTP while the naming scheme is defined by URI/IRI. Contrary to traditional RPC protocols which usually only support one syntax, REST is actually independent from a particular syntax. To upkeep interoperability both client and server though need do negotiate about it, which HTTP itself supports through the Accept request and Content-Type response headers. As long as client and server support HTTP, URI/IRI and a set of negotiated representation formats, defined by backing hypermedia capable media-types, they will be able to interact with each other. In a more narrow sense REST therefore has no API other than HTTP, URI/IRI and the respective media types.
However, things are unfortunately not that easy. Most people unfortunately understand something very different in terms of REST or REST API. While URIs should not convey any semantics itself, after all they are just pointers to a resource, plenty of programmers attribute more importance to URIs than they should. Some clients i.e. will attempt to extract some knowledge off of URIs or consider URIs to return responses that represent a certain type. I.e. it may seem natural to consider an URI such as https://api.acme.org/users/1 to return a representation that describes a particular user of that particualar system. An external documentation may specify that a JSON structure is returned that follows a given template such as
{
"id": 1,
"firstName": "Roman",
"lastName": "Vottner",
"role": "Admin",
...
}
can be expected, however, such a thing is closer to RPC than it is to REST. Neither is the response self-descriptive, as required by REST, nor does it follow a representation format that follows a well defined media type that defines the syntax and each of the elements that may form a message. Clients therefore are usually tailor-made for exactly one particular system (or REST API if you will) and can't be used to interact with different systems out of the box without further manual integration/updates. External documentation such as OpenAPI or Swagger are used to describe the available endpoints, the payload-templates that a server will be able to process as well as the expected responses, depending on the input. These documentation therefore is the truth and thus defines the API a client can look up or even use to autogenerate stub classes to interact with the server-side, similar to SOAP.
I therefore don't agree with the answer given by dave. While for RPC systems or the common understood term of REST API his definition may be suitable, for actual REST architectures his explanation isn't fitting at all and thus, IMO at least, not correct either. REST isn't a collection of rules, standards and/or guidelines. It is a set of few constraints that just ensure that peers in such an architecture avoid coupling, support future evolution and become more robust to change.
API is basically a set of functions and procedures which allow one application to access the feature of other application
REST is a set of rules or guidelines to build a web API.
It is basically an architectural style for networked applications on the web which is limited to client-server based applications.
Read more at: https://www.freelancinggig.com/blog/2018/11/02/what-is-the-difference-between-api-and-rest-api/
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 months ago.
The community reviewed whether to reopen this question 4 months ago and left it closed:
Original close reason(s) were not resolved
Improve this question
I'm getting involved in a project where some senior team members believe that a REST API has to be HATEOAS compliant and implement all Richardson's maturity levels (http://martinfowler.com/articles/richardsonMaturityModel.html)!
AFAIK most REST implementations are not HATEOAS compliant and there should be a good reason why more people aren't doing it. I can think of reasons like added complexity, lack of frameworks (server and client sides), and performance concern.
What do you think? Have you had any experience with HATEOAS in a real world project?
Nobody in the REST community says REST is easy. HATEOAS is just one of the aspects that adds difficulty to a REST architecture.
People don't do HATEOAS for all the reasons you suggest: it's difficult. It adds complexity to both the server-side and the client (if you actually want to benefit from it).
HOWEVER, billions of people experience the benefits of REST today. Do you know what the "checkout" URL is at Amazon? I don't. Yet, I can checkout every day. Has that URL changed? I don't know it, I don't care.
Do you know who does care? Anyone who's written a screen-scraped Amazon automated client. Someone who has likely painstakingly sniffed web traffic, read HTML pages, etc. to find what links to call when and with what payloads.
And as soon as Amazon changed their internal processes and URL structure, those hard-coded clients failed -- because the links broke.
Yet, the casual web surfers were able to shop all day long with hardly a hitch.
That's REST in action, it's just augmented by the human being that is able to interpret and intuit the text-based interface, recognize a small graphic with a shopping cart, and suss out what that actually means.
Most folks writing software don't do that. Most folks writing automated clients don't care. Most folks find it easier to fix their clients when they break than engineer the application to not break in the first place. Most folks simply don't have enough clients where it matters.
If you're writing an internal API to communicate between two systems with expert tech support and IT on both sides of the traffic, who are able to communicate changes quickly, reliably, and with a schedule of change, then REST buys you nothing. You don't need it, your app isn't big enough, and it's not long-lived enough to matter.
Large sites with large user bases do have this problem. They can't just ask folks to change their client code on a whim when interacting with their systems. The server's development schedule is not the same as the client development schedule. Abrupt changes to the API are simply unacceptable to everyone involved, as it disrupts traffic and operations on both sides.
So, an operation like that would very likely benefit from HATEOAS, as it's easier to version, easier for older clients to migrate, easier to be backward compatible than not.
A client that delegates much of its workflow to the server and acts upon the results is much more robust to server changes than a client that does not.
But most folks don't need that flexibility. They're writing server code for 2 or 3 departments, it's all internal use. If it breaks, they fix it, and they've factored that into their normal operations.
Flexibility, whether from REST or anything else, breeds complexity. If you want it simple, and fast, then you don't make it flexible, you "just do it", and be done. As you add abstractions and dereferencing to systems, then stuff gets more difficult, more boilerplate, more code to test.
Much of REST fails the "you're not going to need it" bullet point. Until, of course, you do.
If you need it, then use it, and use it as it's laid out. REST is not shoving stuff back and forth over HTTP. It never has been, it's a much higher level than that.
But when you do need REST, and you do use REST, then HATEOAS is a necessity. It's part of the package and a key to what makes it work at all.
Example:- To understand it better let’s look at the below response of retrieve user with id 123 from the server (http://localhost:8080/user/123):
{
"name": "John Doe",
"links": [{
"rel": "self",
"href": "http://localhost:8080/user/123"
},
{
"rel": "posts",
"href": "http://localhost:8080/user/123/post"
},
{
"rel": "address",
"href": "http://localhost:8080/user/123/address"
}
]
}
Yes, I have had some experience with hypermedia in APIs. Here are some of the benefits:
Explorable API:
It may sound trivial but do not underestimate the power of an explorable API. The ability to browse around the data makes it a lot easier for the client developers to build a mental model of the API and its data structures.
Inline documentation:
The use of URLs as link relations can point client developers to documentation.
Simple client logic:
A client that simply follows URLs instead of constructing them itself, should be easier to implement and maintain.
The server takes ownership of URL structures:
The use of hypermedia removes the client's hard coded knowledge of the URL structures used by the server.
Off loading content to other services:
Hypermedia is necessary when off-loading content to other servers (a CDN for instance).
Versioning with links:
Hypermedia helps versioning of APIs.
Multiple implementations of the same service/API:
Hypermedia is a necessity when multiple implementations of the same service/API exists. A service could for instance be a blog API with resources for adding posts and comments. If the service is specified in terms of link relations instead of hard coded URLs then the same service may be instantiated multiple times at different URLs, hosted by different companies but still accessible through the same well defined set of links by one single client.
You can find an in-depth explanation of these bullet points here: http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html
(there is a similar question here: https://softwareengineering.stackexchange.com/questions/149124/what-is-the-benefit-of-hypermedia-hateoas where I have given the same explanation)
Richardson's maturity level 3 is valuable and should be adopted. Jørn Wildt has already summarized some advantages and an other answer, by Wilt, complements it very well.
However, Richardson's maturity level 3 is not the same as Fielding's HATEOAS. Richardson's maturity level 3 is only about API design. Fielding's HATEOAS is about API design too, but also prescribes that the client software should not assume that a resource has a specific structure beyond the structure that is defined by the media type. This requires a very generic client, like a web browser, which doesn't have knowledge about specific websites. Since Roy Fielding has coined the term REST and has set HATEOAS as a requirement for compliance to REST, the question is: do we want to adopt HATEOAS and if not, can we still call our API RESTful or not? I think we can. Let me explain.
Suppose we have achieved HATEOAS. The client-side of the application is now very generic, but most likely, the user experience is bad, because without any knowledge of the semantics of the resources, the presentation of the resources cannot be tailored to reflect those semantics. If resource 'car' and resource 'house' have the same media type (e.g. application/json), then they will be presented to the user in the same way, for example as a table of properties (name/value pairs).
But okay, our API is really RESTful.
Now, suppose we build a second client application on top of this API. This second client violates the HATEOAS ideas and has hard-coded information about the resources. It displays a car and a house in different ways.
Can the API still be called RESTful? I think so. It is not the API's fault that one of its clients has violated HATEOAS.
I advise to build RESTful APIs, i.e. APIs for which a generic client can be implemented in theory, but in most cases, you need some hard-coded information about resources in your client in order to satisfy the usability requirements. Still, try to hard-code as little as possible, to reduce the dependencies between client and server.
I have included a section on HATEOAS in my REST implementation pattern called JAREST.
We are building a REST level 3 API where our response is in HAL-Json.
HATEOAS is great for both front and back-end but it comes with challenges. We made some customizations/additions for also managing ACL inside the HAL-Json response (which doesn't break the HAL-Json standard).
The biggest advantages to HATEOAS I see is that we do not need to write/guess any urls on our front-end application. All you need is a entry point (https://hostname) and from there on you can just browse your way through the resources using the links or templated links provided inside the response.
Like that versioning can be handled easily, renaming/replacing urls, extending resources with additional relations without breaking front-end code.
Caching of resources on front-end is a piece of cake using the self links.
We also push resources to clients through a socket connection, since those are also rendered in HAL we could easily add them to cache the same way.
Another advantage of using HAL-Json is that it is clear what the response model should look like, since there is a documented standard that should be followed.
One of our customizations is that we added an actions object inside the self-link object that exposes to the front end which actions or CRUD operations the authenticated user is allowed to perform on the respective resource (create:POST, read:GET, update:PUT, edit:PATCH, delete:DELETE). Like this our front end ACL is totally dictated by our REST API response, moving this responsibility fully to the the back-end model.
So to give a quick example you could have a post object in HAL-Json that looks something like this:
{
"_links": {
"self": {
"href": "https://hostname/api/v1/posts/1",
"actions": {
"read": "GET",
"update": "PUT",
"delete": "DELETE"
}
}
},
"_embedded": {
"owner": {
"id": 1,
"name": "John Doe",
"email": "john.doe#example.com",
"_links": {
"self": {
"href": "https://hostname/api/v1/users/1",
"actions": {
"read": "GET"
}
}
}
}
},
"subject": "Post subject",
"body": "Post message body"
}
Now all we have to do on front end is build a AclService with an isAllowed method that checks whether the action we want to perform is in the actions object.
Currently on front-end it looks as simple as: post.isAllowed('delete');
I think REST level 3 is great, but it can lead to some headaches. You will need to have a great understanding of REST and if you want to work with level 3 REST I would suggest to follow the REST concept strictly otherwise you will easily get lost on your way when implementing it.
In our case we have the advantage that we are building both front and back-end but in principle it should NOT make a difference.
But a common pitfall I have seen in our team is that some developers try to solve front-end issues (architecture) by changing their back-end model so it "suits" the front-end needs.
I have used HATEOAS in some real projects, but with a different interpretation than Richardson. If that is what your bosses want, then I guess you should just do it. I take HATEOAS to mean that your resources should include an HTML doctype, hyperlinks to related resources and HTML forms to expose functionality for verbs other than GET. (This is when the Accept type is text/html - other content types don't require these extras.) I don't know where the belief that all REST resources in your entire application have to be glued together came from. A network application should contain multiple resources that may or may not be directly related. Or why it is believed that XML, JSON and other types need to follow this. (HATEOAS is HTML-specific.)
I have read articles about the differences between SOAP and REST as a web service communication protocol, but I think that the biggest advantages for REST over SOAP are:
REST is more dynamic, no need to create and update UDDI(Universal Description, Discovery, and Integration).
REST is not restricted to only XML format. RESTful web services can send plain text/JSON/XML.
But SOAP is more standardized (E.g.: security).
So, am I correct in these points?
Unfortunately, there are a lot of misinformation and misconceptions around REST. Not only your question and the answer by #cmd reflect those, but most of the questions and answers related to the subject on Stack Overflow.
SOAP and REST can't be compared directly, since the first is a protocol (or at least tries to be) and the second is an architectural style. This is probably one of the sources of confusion around it, since people tend to call REST any HTTP API that isn't SOAP.
Pushing things a little and trying to establish a comparison, the main difference between SOAP and REST is the degree of coupling between client and server implementations. A SOAP client works like a custom desktop application, tightly coupled to the server. There's a rigid contract between client and server, and everything is expected to break if either side changes anything. You need constant updates following any change, but it's easier to ascertain if the contract is being followed.
A REST client is more like a browser. It's a generic client that knows how to use a protocol and standardized methods, and an application has to fit inside that. You don't violate the protocol standards by creating extra methods, you leverage on the standard methods and create the actions with them on your media type. If done right, there's less coupling, and changes can be dealt with more gracefully. A client is supposed to enter a REST service with zero knowledge of the API, except for the entry point and the media type. In SOAP, the client needs previous knowledge on everything it will be using, or it won't even begin the interaction. Additionally, a REST client can be extended by code-on-demand supplied by the server itself, the classical example being JavaScript code used to drive the interaction with another service on the client-side.
I think these are the crucial points to understand what REST is about, and how it differs from SOAP:
REST is protocol independent. It's not coupled to HTTP. Pretty much like you can follow an ftp link on a website, a REST application can use any protocol for which there is a standardized URI scheme.
REST is not a mapping of CRUD to HTTP methods. Read this answer for a detailed explanation on that.
REST is as standardized as the parts you're using. Security and authentication in HTTP are standardized, so that's what you use when doing REST over HTTP.
REST is not REST without hypermedia and HATEOAS. This means that a client only knows the entry point URI and the resources are supposed to return links the client should follow. Those fancy documentation generators that give URI patterns for everything you can do in a REST API miss the point completely. They are not only documenting something that's supposed to be following the standard, but when you do that, you're coupling the client to one particular moment in the evolution of the API, and any changes on the API have to be documented and applied, or it will break.
REST is the architectural style of the web itself. When you enter Stack Overflow, you know what a User, a Question and an Answer are, you know the media types, and the website provides you with the links to them. A REST API has to do the same. If we designed the web the way people think REST should be done, instead of having a home page with links to Questions and Answers, we'd have a static documentation explaining that in order to view a question, you have to take the URI stackoverflow.com/questions/<id>, replace id with the Question.id and paste that on your browser. That's nonsense, but that's what many people think REST is.
This last point can't be emphasized enough. If your clients are building URIs from templates in documentation and not getting links in the resource representations, that's not REST. Roy Fielding, the author of REST, made it clear on this blog post: REST APIs must be hypertext-driven.
With the above in mind, you'll realize that while REST might not be restricted to XML, to do it correctly with any other format you'll have to design and standardize some format for your links. Hyperlinks are standard in XML, but not in JSON. There are draft standards for JSON, like HAL.
Finally, REST isn't for everyone, and a proof of that is how most people solve their problems very well with the HTTP APIs they mistakenly called REST and never venture beyond that. REST is hard to do sometimes, especially in the beginning, but it pays over time with easier evolution on the server side, and client's resilience to changes. If you need something done quickly and easily, don't bother about getting REST right. It's probably not what you're looking for. If you need something that will have to stay online for years or even decades, then REST is for you.
REST vs SOAP is not the right question to ask.
REST, unlike SOAP is not a protocol.
REST is an architectural style and a design for network-based software architectures.
REST concepts are referred to as resources. A representation of a resource must be stateless. It is represented via some media type. Some examples of media types include XML, JSON, and RDF. Resources are manipulated by components. Components request and manipulate resources via a standard uniform interface. In the case of HTTP, this interface consists of standard HTTP ops e.g. GET, PUT, POST, DELETE.
#Abdulaziz's question does illuminate the fact that REST and HTTP are often used in tandem. This is primarily due to the simplicity of HTTP and its very natural mapping to RESTful principles.
Fundamental REST Principles
Client-Server Communication
Client-server architectures have a very distinct separation of concerns. All applications built in the RESTful style must also be client-server in principle.
Stateless
Each client request to the server requires that its state be fully represented. The server must be able to completely understand the client request without using any server context or server session state. It follows that all state must be kept on the client.
Cacheable
Cache constraints may be used, thus enabling response data to be marked as cacheable or not-cacheable. Any data marked as cacheable may be reused as the response to the same subsequent request.
Uniform Interface
All components must interact through a single uniform interface. Because all component interaction occurs via this interface, interaction with different services is very simple. The interface is the same! This also means that implementation changes can be made in isolation. Such changes, will not affect fundamental component interaction because the uniform interface is always unchanged. One disadvantage is that you are stuck with the interface. If an optimization could be provided to a specific service by changing the interface, you are out of luck as REST prohibits this. On the bright side, however, REST is optimized for the web, hence incredible popularity of REST over HTTP!
The above concepts represent defining characteristics of REST and differentiate the REST architecture from other architectures like web services. It is useful to note that a REST service is a web service, but a web service is not necessarily a REST service.
See this blog post on REST Design Principles for more details on REST and the above stated bullets.
EDIT: update content based on comments
SOAP (Simple Object Access Protocol) and REST (Representation State Transfer) both are beautiful in their way. So I am not comparing them. Instead, I am trying to depict the picture, when I preferred to use REST and when SOAP.
What is payload?
When data is sent over the Internet, each unit transmitted includes both header information and the actual data being sent. The header identifies the source and destination of the packet, while the actual data is referred to as the payload. In general, the payload is the data that is carried on behalf of an application and the data received by the destination system.
Now, for example, I have to send a Telegram and we all know that the cost of the telegram will depend on some words.
So tell me among below mentioned these two messages, which one is cheaper to send?
<name>Arin</name>
or
"name": "Arin"
I know your answer will be the second one although both representing the same message second one is cheaper regarding cost.
So I am trying to say that, sending data over the network in JSON format is cheaper than sending it in XML format regarding payload.
Here is the first benefit or advantages of REST over SOAP. SOAP only support XML, but REST supports different format like text, JSON, XML, etc. And we already know, if we use Json then definitely we will be in better place regarding payload.
Now, SOAP supports the only XML, but it also has its advantages.
Really! How?
SOAP relies on XML in three ways
Envelope – that defines what is in the message and how to process it.
A set of encoding rules for data types, and finally the layout of the procedure calls and responses gathered.
This envelope is sent via a transport (HTTP/HTTPS), and an RPC (Remote Procedure Call) is executed, and the envelope is returned with information in an XML formatted document.
The important point is that one of the advantages of SOAP is the use of the “generic” transport but REST uses HTTP/HTTPS. SOAP can use almost any transport to send the request but REST cannot. So here we got an advantage of using SOAP.
As I already mentioned in above paragraph “REST uses HTTP/HTTPS”, so go a bit deeper on these words.
When we are talking about REST over HTTP, all security measures applied HTTP are inherited, and this is known as transport level security and it secures messages only while it is inside the wire but once you delivered it on the other side you don’t know how many stages it will have to go through before reaching the real point where the data will be processed. And of course, all those stages could use something different than HTTP.So Rest is not safer completely, right?
But SOAP supports SSL just like REST additionally it also supports WS-Security which adds some enterprise security features. WS-Security offers protection from the creation of the message to it’s consumption. So for transport level security whatever loophole we found that can be prevented using WS-Security.
Apart from that, as REST is limited by it's HTTP protocol so it’s transaction support is neither ACID compliant nor can provide two-phase commit across distributed transnational resources.
But SOAP has comprehensive support for both ACID based transaction management for short-lived transactions and compensation based transaction management for long-running transactions. It also supports two-phase commit across distributed resources.
I am not drawing any conclusion, but I will prefer SOAP-based web service while security, transaction, etc. are the main concerns.
Here is the "The Java EE 6 Tutorial" where they have said A RESTful design may be appropriate when the following conditions are met. Have a look.
Hope you enjoyed reading my answer.
REST(REpresentational State Transfer)
REpresentational State of an Object is Transferred is REST i.e. we don't send Object, we send state of Object.
REST is an architectural style. It doesn’t define so many standards like SOAP. REST is for exposing Public APIs(i.e. Facebook API, Google Maps API) over the internet to handle CRUD operations on data. REST is focused on accessing named resources through a single consistent interface.
SOAP(Simple Object Access Protocol)
SOAP brings its own protocol and focuses on exposing pieces of application logic (not data) as services. SOAP exposes operations. SOAP is focused on accessing named operations, each operation implement some business logic. Though SOAP is commonly referred to as web services this is misnomer. SOAP has a very little if anything to do with the Web. REST provides true Web services based on URIs and HTTP.
Why REST?
Since REST uses standard HTTP it is much simpler in just about ever way.
REST is easier to implement, requires less bandwidth and resources.
REST permits many different data formats where as SOAP only permits XML.
REST allows better support for browser clients due to its support for JSON.
REST has better performance and scalability. REST reads can be cached, SOAP based reads cannot be cached.
If security is not a major concern and we have limited resources. Or we want to create an API that will be easily used by other developers publicly then we should go with REST.
If we need Stateless CRUD operations then go with REST.
REST is commonly used in social media, web chat, mobile services and Public APIs like Google Maps.
RESTful service return various MediaTypes for the same resource, depending on the request header parameter "Accept" as application/xml or application/json for POST and /user/1234.json or GET /user/1234.xml for GET.
REST services are meant to be called by the client-side application and not the end user directly.
ST in REST comes from State Transfer. You transfer the state around instead of having the server store it, this makes REST services scalable.
Why SOAP?
SOAP is not very easy to implement and requires more bandwidth and resources.
SOAP message request is processed slower as compared to REST and it does not use web caching mechanism.
WS-Security: While SOAP supports SSL (just like REST) it also supports WS-Security which adds some enterprise security features.
WS-AtomicTransaction: Need ACID Transactions over a service, you’re going to need SOAP.
WS-ReliableMessaging: If your application needs Asynchronous processing and a guaranteed level of reliability and security. Rest doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying.
If the security is a major concern and the resources are not limited then we should use SOAP web services. Like if we are creating a web service for payment gateways, financial and telecommunication related work then we should go with SOAP as here high security is needed.
source1
source2
IMHO you can't compare SOAP and REST where those are two different things.
SOAP is a protocol and REST is a software architectural pattern. There is a lot of misconception in the internet for SOAP vs REST.
SOAP defines XML based message format that web service-enabled applications use to communicate each other over the internet. In order to do that the applications need prior knowledge of the message contract, datatypes, etc..
REST represents the state(as resources) of a server from an URL.It is stateless and clients should not have prior knowledge to interact with server beyond the understanding of hypermedia.
First of all: officially, the correct question would be web services + WSDL + SOAP vs REST.
Because, although the web service, is used in the loose sense, when using the HTTP protocol to transfer data instead of web pages, officially it is a very specific form of that idea. According to the definition, REST is not "web service".
In practice however, everyone ignores that, so let's ignore it too
There are already technical answers, so I'll try to provide some intuition.
Let's say you want to call a function in a remote computer, implemented in some other programming language (this is often called remote procedure call/RPC). Assume that function can be found at a specific URL, provided by the person who wrote it. You have to (somehow) send it a message, and get some response. So, there are two main questions to consider.
what is the format of the message you should send
how should the message be carried back and forth
For the first question, the official definition is WSDL. This is an XML file which describes, in detailed and strict format, what are the parameters, what are their types, names, default values, the name of the function to be called, etc. An example WSDL here shows that the file is human-readable (but not easily).
For the second question, there are various answers. However, the only one used in practice is SOAP. Its main idea is: wrap the previous XML (the actual message) into yet another XML (containing encoding info and other helpful stuff), and send it over HTTP. The POST method of the HTTP is used to send the message, since there is always a body.
The main idea of this whole approach is that you map a URL to a function, that is, to an action. So, if you have a list of customers in some server, and you want to view/update/delete one, you must have 3 URLS:
myapp/read-customer and in the body of the message, pass the id of the customer to be read.
myapp/update-customer and in the body, pass the id of the customer, as well as the new data
myapp/delete-customer and the id in the body
The REST approach sees things differently. A URL should not represent an action, but a thing (called resource in the REST lingo). Since the HTTP protocol (which we are already using) supports verbs, use those verbs to specify what actions to perform on the thing.
So, with the REST approach, customer number 12 would be found on URL myapp/customers/12. To view the customer data, you hit the URL with a GET request. To delete it, the same URL, with a DELETE verb. To update it, again, the same URL with a POST verb, and the new content in the request body.
For more details about the requirements that a service has to fulfil to be considered truly RESTful, see the Richardson maturity model. The article gives examples, and, more importantly, explains why a (so-called) SOAP service, is a level-0 REST service (although, level-0 means low compliance to this model, it's not offensive, and it is still useful in many cases).
Among many others already covered in the many answers, I would highlight that SOAP enables to define a contract, the WSDL, which define the operations supported, complex types, etc.
SOAP is oriented to operations, but REST is oriented at resources.
Personally I would select SOAP for complex interfaces between internal enterprise applications, and REST for public, simpler, stateless interfaces with the outside world.
Addition for:
++ A mistake that’s often made when approaching REST is to think of it as “web services with URLs”—to think of REST as another remote procedure call (RPC) mechanism, like SOAP, but invoked through plain HTTP URLs and without SOAP’s hefty XML namespaces.
++ On the contrary, REST has little to do with RPC. Whereas RPC is service oriented and focused on actions and verbs, REST is resource oriented, emphasizing the things and nouns that comprise an application.
A lot of these answers entirely forgot to mention hypermedia controls (HATEOAS) which is completely fundamental to REST. A few others touched on it, but didn't really explain it so well.
This article should explain the difference between the concepts, without getting into the weeds on specific SOAP features.
REST API
RESTful APIs are the most famous type of API. REST stands REpresentational State Transfer.
REST APIs are APIs that follow standardized principles, properties, and constraints.
You can access resources in the REST API using HTTP verbs.
REST APIs operate on a simple request/response system. You can send a request using these HTTP methods:
GET
POST
PUT
PATCH
DELETE
TRACE
OPTIONS
CONNECT
HEAD
Here are the most common HTTP verbs
GET (read existing data)
POST (create a new response or data)
PATCH (update the data)
DELETE (delete the data)
The client can make requests using HTTP verbs followed by the endpoint.
The endpoint (or route) is the URL you request for. The path determines the resource you’re requesting.
When you send a request to an endpoint, it responds with the relevant data, generally formatted as JSON, XML, plain text, images, HTML, and more.
REST APIs can also be designed with many different endpoints that return different types of data. Accessing multiple endpoints with a REST API requires various API calls.
An actual RESTful API follows the following five constraints:
Client-Server Architecture
The client requests the data from the server with no third-party interpretation.
Statelessness
Statelessness means that every HTTP request happens in complete isolation. Each request contains the information necessary to service the request. The server never relies on information from previous requests. There’s no state.
Cacheability
Responses can be explicitly or implicitly defined as cacheable or non-cacheable to improve scalability and performance. For example, enabling the cache of GET requests can improve the response times of requests for resource data.
Layering
Different layers of the API architecture should work together, creating a scalable system that is easy to update or adjust.
Uniform Interface
Communication between the client and the server must be done in a standardized language that is independent of both. This improves scalability and flexibility.
REST APIs are a good fit for projects that need to be
Flexible
Scalable
Fast
SOAP API
SOAP is a necessary protocol that helped introduce the widespread use of APIs.
SOAP is the acronym for Simple Object Access Protocol.
SOAP is a standardized protocol that relies on XML to make requests and receive responses.
Even though SOAP is based on XML, the SOAP protocol is still in wide usage.
SOAP APIs make data available as a service and are typically used when performing transactions involving multiple API calls or applications where security is the primary consideration.
SOAP was initially developed for Microsoft in 1998 to provide a standard mechanism for integrating services on the internet regardless of the operating system, object model, or programming language.
The “S” in SOAP stands for Simple, and for a good reason — SOAP can be used with less complexity as it requires less coding in the app layer for transactions, security, and other functions.
SOAP has three primary characteristics:
Extensibility of SOAP API
SOAP allows for extensions that introduce more robust features, such as Windows Server Security, Addressing, and more.
Neutrality of SOAP API
SOAP is capable of operating over a wide range of protocols, like UDP, JMS, SMTP, TCP, and HTTP.can operate.
Independence of SOAP API
SOAP API responses are purely based on XML. Therefore SOAP APIs are platform and language independent.
Developers continue to debate the pros and cons of using SOAP and REST. The best one for your project will be the one that aligns with your needs.
SOAP APIs remain a top choice for corporate entities and government organizations that prioritize security, even though REST has largely dominated web applications.
SOAP is more secure than REST as it uses WS-Security for transmission along with Secure Socket Layer
SOAP also has more excellent transactional reliability, which is another reason why SOAP historically has been favored by the banking industry and other large entities.
What is REST
REST stands for representational state transfer, it's actually an architectural style for creating Web API which treats everything(data or functionality) as recourse.
It expects; exposing resources through URI and responding in multiple formats and representational transfer of state of the resources in stateless manner. Here I am talking about two things:
Stateless manner: Provided by HTTP.
Representational transfer of state: For example if we are adding an employee. .
into our system, it's in POST state of HTTP, after this it would be in GET state of HTTP, PUT and DELETE likewise.
REST can use SOAP web services because it is a concept and can use any protocol like HTTP, SOAP.SOAP uses services interfaces to expose the business logic. REST uses URI to expose business logic.
REST is not REST without HATEOAS. This means that a client only knows the entry point URI and the resources are supposed to return links the client should follow. Those fancy documentation generators that give URI patterns for everything you can do in a REST API miss the point completely. They are not only documenting something that's supposed to be following the standard, but when you do that, you're coupling the client to one particular moment in the evolution of the API, and any changes on the API have to be documented and applied, or it will break.
HATEOAS, an abbreviation for Hypermedia As The Engine Of Application State, is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers. A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in some service-oriented architectures (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).
Reference 1
Reference 2
Although SOAP and REST share similarities over the HTTP protocol, SOAP is a more rigid set of messaging patterns than REST. The rules in SOAP are relevant because we can’t achieve any degree of standardization without them. REST needs no processing as an architecture style and is inherently more versatile. In the spirit of information exchange, both SOAP and REST depend on well-established laws that everybody has decided to abide by.
The choice of SOAP vs. REST is dependent on the programming language you are using the environment you are using and the specifications.
To answer this question it’s useful to understand the evolution of the architecture of distributed applications from simple layered architectures, to object & service based, to resources based, & nowadays we even have event based architectures. Most large systems use a combination of styles.
The first distributed applications had layered architectures. I'll assume everyone here knows what layers are. These structures are neatly organized, and can be stacks or cyclical structures. Effort is made to maintain a unidirectional data flow.
Object-based architectures evolved out of layered architectures and follow a much looser model. Here, each component is an object (often called a distributed object). The objects interact with one another using a mechanism similar to remote procedure calls - when a client binds to a distributed object it loads an implementation of the objects interface into its address space. The RPC stub can marshal a request & receive a response. Likewise the objects interface on the server is an RPC style stub. The structure of these object based systems is not as neatly organized, it looks more like an object graph.
The interface of a distributed object conceals its implementation. As with layered components, if the interface is clearly defined the internal implementation can be altered - even replaced entirely.
Object-based architectures provide the basis for encapsulating services. A service is provided by a self-contained entity, though internally it can make use of other services. Gradually object-based architectures evolved into service-oriented architectures (SOAs).
With SOA, a distributed application is composed of services. These services can be provided across administrative domains - they may be available across the web (i.e. a storage service offered by a cloud provider).
As web services became popular, and more applications started using them, service composition (combining services to form new ones) became more important. One of the problems with SOA was that integrating different services could become extremely complicated.
While SOAP is a protocol, its use implies a service oriented architecture. SOAP attempted to provide a standard for services whereby they would be composable and easily integrated.
Resource-based architectures were a different approach to solving the integration problems of SOA. The idea is to treat the distributed system as a giant collection of resources that are individually managed by components.
This led to the development of RESTful architectures. One thing that characterizes RESTful services is stateless execution. This is different than SOA where the server maintains the state.
So… how do service-specific interfaces, as provided by service-oriented architectures (including those that use SOAP) compare with resource-based architecture like REST?
While REST is simple, it does not provide a simple interface for complex communication schemes. For example, if you are required to use transactions REST is not appropriate, it is better to keep the complex state encapsulated on the server than have the client manage the transaction. But there are many scenarios where the orthogonal use of resources in RESTful architectures greatly simplifies integration of services in what would otherwise mean an explosion of service interfaces. Another tradeoff is resource-based architectures put more complexity on the client & increase traffic over the network while service-based increase the complexity of the server & tax its memory & CPU resources.
Some people have also mentioned common HTTP services or other services that do not satisfy the requirements of RESTful architecture or SOAP. These too can be categorized as either service-based or resource-based. These have the advantage of being simpler to implement. You'd only use such an approach if you knew your service will never need to be integrated across administrative domains since this makes no attempt at fixing the integration issues that arise.
These sorts of HTTP-based services, especially Pseudo-RESTful services are still the most common types. Implementing SOAP is complicated and should only be used if you really need it - i.e. you need a service that's easily integrated across domains and you want it to have a service-interface. There are still cases where this is needed. A true RESTful service is also difficult to implement, though not as difficult as SOAP.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
I was under the assumption that REST was a web service but it seems that I am incorrect in thinking this - so, what is REST?
I've read through Wikipedia but still cant quite wrap my head around it. Why to do many places refer to API's as REST API's?
REST is not a specific web service but a design concept (architecture) for managing state information. The seminal paper on this was Roy Thomas Fielding's dissertation (2000), "Architectural Styles and the Design of Network-based Software Architectures" (available online from the University of California, Irvine).
First read Ryan Tomayko's post How I explained REST to my wife; it's a great starting point. Then read Fielding's actual dissertation. It's not that advanced, nor is it long (six chapters, 180 pages)! (I know you kids in school like it short).
EDIT: I feel it's pointless to try to explain REST. It has so many concepts like scalability, visibility (stateless) etc. that the reader needs to grasp, and the best source for understanding those are the actual dissertation. It's much more than POST/GET etc.
REST is a software design pattern typically used for web applications. In layman's terms this means that it is a commonly used idea used in many different projects. It stands for REpresentational State Transfer. The basic idea of REST is treating objects on the server-side (as in rows in a database table) as resources than can be created or destroyed.
The most basic way of thinking about REST is as a way of formatting the URLs of your web applications. For example, if your resource was called "posts", then:
/posts Would be how a user would access ALL the posts, for displaying.
/posts/:id Would be how a user would access and view an individual post, retrieved based on their unique id.
/posts/new Would be how you would display a form for creating a new post.
Sending a POST request to /users would be how you would actually create a new post on the database level.
Sending a PUT request to /users/:id would be how you would update the attributes of a given post, again identified by a unique id.
Sending a DELETE request to /users/:id would be how you would delete a given post, again identified by a unique id.
As I understand it, the REST pattern was mainly popularized (for web apps) by the Ruby on Rails framework, which puts a big emphasis on RESTful routes. I could be wrong about that though.
I may not be the most qualified to talk about it, but this is how I've learned it (specifically for Rails development).
When someone refers to a "REST api," generally what they mean is an api that uses RESTful urls for retrieving data.
REST is an architectural style and a design for network-based software architectures.
REST concepts are referred to as resources. A representation of a resource must be stateless. It is represented via some media type. Some examples of media types include XML, JSON, and RDF. Resources are manipulated by components. Components request and manipulate resources via a standard uniform interface. In the case of HTTP, this interface consists of standard HTTP ops e.g. GET, PUT, POST, DELETE.
REST is typically used over HTTP, primarily due to the simplicity of HTTP and its very natural mapping to RESTful principles. REST however is not tied to any specific protocol.
Fundamental REST Principles
Client-Server Communication
Client-server architectures have a very distinct separation of concerns. All applications built in the RESTful style must also be client-server in principle.
Stateless
Each client request to the server requires that its state be fully represented. The server must be able to completely understand the client request without using any server context or server session state. It follows that all state must be kept on the client. We will discuss stateless representation in more detail later.
Cacheable
Cache constraints may be used, thus enabling response data to to be marked as cacheable or not-cachable. Any data marked as cacheable may be reused as the response to the same subsequent request.
Uniform Interface
All components must interact through a single uniform interface. Because all component interaction occurs via this interface, interaction with different services is very simple. The interface is the same! This also means that implementation changes can be made in isolation. Such changes, will not affect fundamental component interaction because the uniform interface is always unchanged. One disadvantage is that you are stuck with the interface. If an optimization could be provided to a specific service by changing the interface, you are out of luck as REST prohibits this. On the bright side, however, REST is optimized for the web, hence incredible popularity of REST over HTTP!
The above concepts represent defining characteristics of REST and differentiate the REST architecture from other architectures like web services. It is useful to note that a REST service is a web service, but a web service is not necessarily a REST service.
See this blog post on REST Design Principals for more details on REST and the above principles.
It stands for Representational State Transfer and it can mean a lot of things, but usually when you are talking about APIs and applications, you are talking about REST as a way to do web services or get programs to talk over the web.
REST is basically a way of communicating between systems and does much of what SOAP RPC was designed to do, but while SOAP generally makes a connection, authenticates and then does stuff over that connection, REST works pretty much the same way that that the web works. You have a URL and when you request that URL you get something back. This is where things start getting confusing because people describe the web as a the largest REST application and while this is technically correct it doesn't really help explain what it is.
In a nutshell, REST allows you to get two applications talking over the Internet using tools that are similar to what a web browser uses. This is much simpler than SOAP and a lot of what REST does is says, "Hey, things don't have to be so complex."
Worth reading:
How I Explained REST to My Wife (now available here)
Architectural Styles and the Design of Network-based Software Architectures
http://en.wikipedia.org/wiki/Representational_State_Transfer
The basic idea is that instead of having an ongoing connection to the server, you make a request, get some data, show that to a user, but maybe not all of it, and then when the user does something which calls for more data, or to pass some up to the server, the client initiates a change to a new state.