I am really new to programming, and having some trouble understanding the concept of RESTful APIs. I've read about REST and RESTful APIs. I've looked through the questions already asked here in SO, but can't seem to get any better understanding of the subject.
In my network programming class I'm working with socket programming. There are two parts, part A and part B, in the task.
In part A I've programmed a server that responds to GET and POST. The server either retrieves the file asked for by the client, or writes to the file. (HTTP-protocol is used).
In part B I'm to use HTTP to implement a RESTful application. Basically it is a message server with the ability to handle GET, POST, PUT and DELETE. In this part the server is to create and interact with an xml-file. I understand how the methods work. But what I really don't understand is the following:
Why is the server in part A non-RESTful, while it is RESFTful in part B?
REST is an architectural style (not a protocol like SOAP, not a technology itself or even not an implementation, it is basically a set of a rule), This architecture offers some constraints for using HTTP. If you stick by this architectural constraints while using HTTP, it is called RESTful, otherwise, it is not-RESTful.
list of these architectural constraints here.
resource and more details wikipedia
in part A, what you wrote was just a HTTP end point. Its not a REST 'service'. Maybe you can check this link out for more explanation :
What is the difference between HTTP and REST?
Also, this link provides more info related to that - What is the advantage of using REST instead of non-REST HTTP?
Related
I'm not sure I understand correctly the notion of RESTful API. If I understand correctly, such an API should provide functions you can trigger with GET, POST, PUT & DELETE requests. My question is: if an API only provides POST requests functions, is it still RESTful?
You should probably watch this lecture and read this article.
REST a such has nothing to do with how much of available HTTP methods you use. So, the quick answer is: yes, it could be considered "restful" (whatever that actually means).
Buuut ... it most likely - isn't. And it has nothing to do with the abuse of POST calls.
The main indicator for this magical "RESTfulness" has nothing really to do with how you make the HTTP request (methods and pretty URLs are pointless worthless as a determining factor).
What matters is the returned data and whether, by looking at this data, you can learn about other resources and actions, that are related the resource in any given endpoint. It's basically about the discover-ability.
REST is a misused term for some time and the community especially at Stackoverflow doesn't even care about its actual intention, the decoupling of clients from server APIs in a distributed system.
Client and server achieve the decoupling by following certain recommendations like avoiding stateful connections where client state is stored at and managed by the server, using unique identifiers for resources (URIs) and further nice-to-have features like cacheability to reduce the workload both server and clients have to perform. While Fieldings dissertation lists 6 constraints, he later on explained some further rules applications following the REST architectural style have to follow and the benefits the system gains by following these. Among these are:
The API should not depend on any single communication protocol and adhere to and not violate the underlying protocol used. Altough REST is used via HTTP most of the time, it is not restricted to this protocol.
Strong focus on resources and their presentation via media-types.
Clients should not have initial knowledge or assumptions on the available resources or their returned state ("typed" resource) in an API but learn them on the fly via issued requests and analyzed responses. This gives the server the opportunity to move arround or rename resources easily without breaking a client implementation.
So, basically, if you limit yourself only to HTTP you somehow already violate the general idea REST tries to impose.
As #tereško mentioned the Richardson maturity model I want to clarify that this model is rather nonsense in the scope of REST. Even if level 3 is reached it does not mean that this architecture follows REST. And any application that hasn't reached level 3 isn't following this architectural style anyways. Note that an application that only partially follows REST isn't actually following it. It's like either properly or not at all.
In regards to RESTful (the dissertation doesn't contain this term) usually one regards a JSON based API exposed via HTTP as such.
To your actual question:
Based on this quote
... such an API should provide functions you can trigger with GET, POST, PUT & DELETE requests
in terms of REST architectural style I'd say NO as you basically use such an API for RPC calls (a relaxed probably JSON based SOAP if you will), limit yourself to HTTP only and do not use the semantics of the underlying HTTP protocol fully; if you follow the JSON based HTTP API crowd the answer is probably it depends on who you ask as there is no precise definition of the term "RESTful" IMO. I'd say no here as well if you trigger functions rather than resources on the server.
Yes. Restful has some guidelines you should follow. As long as you use HTTP verbs correctly and good practices with regards to URLs naming having only POSTs would be OK. If, on the other hand, a POST request in your application can also delete a record, then I would not call it Restful.
I'm really confused everytime I come around this question, what characteristics would help one choosing SOAP over REST or the other way around?
I mean, besides the fact that REST has a compact format compared to SOAP, and the other "minor" or "technical" differences, what are the "obvious" differences that make one of them more suitable for a project and not the other?
Just for the record, I have read all of the other questions (1|2|3|4) regarding this matter on Stack Overflow, and not one of them answered my question.
The difference between REST and SOAP is fundamental, yet they're not that dissimilar. Ultimately, you still need to transfer exactly the same information in order to perform a particular abstract operation. It's entirely easy to make REST rather low-performing by choosing poorly what information to return, and SOAP with MTOM can transfer large binary chunks efficiently. There's even the possibility to use non-XML encodings and connected transports (e.g., XMPP) with SOAP that can make it more efficient than REST.
So don't worry about that!
A much more relevant thing to think about is that SOAP continues to have significantly more advanced tooling support in some languages, and that other languages strongly prefer REST. For example, if you want a Java client for your service, you'll be able to get going with SOAP in minutes: just put the WSDL location through a tooling engine and you've got yourself a basic client. On the other hand, if you're working with a Javascript client then you'll absolutely prefer to deal with the REST interface; Javascript works great with REST.
A key thing to note here is that you can have your service support both SOAP and REST at once (you might need to put them on different endpoints, but that's not very onerous). I do this with a service I support (using Java and Apache CXF) and the overhead of doing both is minimal: the key is that I need a clean abstract interface behind the scenes that both the SOAP and REST interfaces use.
If you just want a simple, visual guide to help you measure SOAP and REST against your applications requirements...
Vijay Prasad Gupta has put together a simple, helpful flow-chart.
Direct link to flow chart:
https://drive.google.com/file/d/0B3zMtAq1Rf-sdVFNdThvNmZWRGc/edit
Link to article:
https://www.linkedin.com/pulse/20140818062318-7933571-soap-vs-rest-flowchart-to-determine-the-right-web-services-protocol-for-your-needs
SOAP is a form of RPC and REST is architecture style that can scale with the web.
REST concerns about the following (copied from RESTful Web Services)
Addressability
Statelessness
Representations
Links and Connectedness
The Uniform Interface
Two great books on REST and have some discussions on the topic that you are interested in.
REST in Practice
Restful Web Services
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.
I have been reading about REST and SOAP, and understand why implementing REST can be beneficial over using a SOAP protocol. However, I still don't understand why there isn't the "WSDL" equivalent in the REST world. I have seen posts saying there is "no need" for the WSDL or that it would be redundant In the REST world, but I don't understand why. Isn't it always useful to programmatically bind to a definition and create proxy classes instead of manually coding? I don't mean to get into a philosophical debate, just looking for the reason there is no WSDL in REST, or why it is not needed. Thanks.
The Web Application Description Language (WADL) is basically the equivalent to WSDL for RESTful services but there's been an ongoing controversy whether something like this is needed at all.
Joe Gregorio has written a nice article about that topic which is worth a read.
WSDL describes service endpoints. REST clients should not be coupled to server endpoints (i.e. should not be aware of in URLs in advance). REST clients are coupled on the media-types that are transfered between the client and server.
It may make sense to auto generate classes on the client to wrap around the returned media-types. However, as soon as you start to create proxy classes around the service interactions you start to obscure the HTTP interactions and risk degenerating back towards a RPC model.
RSDL aims to turn rest like a hypermedia, in other words, it has more information than a service descriptor like WSDL or WADL. For example, it has the information about navigation, like hypertext and hyperlinks.
For example, given a current resource, you have a set os links to another resources related.
However, i didn't find Rest Clients that supports this format or Rest Server Solutions with a feature to auto generate it.
I think there is a long way for a conclusion about it. See the HTML long story and W3C vs Browsers lol.
For more details about Rest like Hypermedia look it: http://en.wikipedia.org/wiki/HATEOAS
Note : Roy Fielding has been criticizing these tendencies in Rest Apis without the hypermidia approach: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
My Conclusion : Now a Days, WADL is more common that Rest and Integration Frameworks like Camel CXF already supports WADL ( generate and consume ), because it is similar to WSDL, therefore most easy to understand in this migration process ( SOAP to REST ).
Let's see the next chapters ;)
Isn't it always useful to programmatically bind to a definition and
create proxy classes instead of manually coding?
Agree wholeheartedly, this is why I use Swagger.io
Swagger is a powerful open source framework backed by a large
ecosystem of tools that helps you design, build, document, and consume
your RESTful APIs.
So basically I use Swagger to describe my models, endpoints, etc, and then I use other tools like swagger-codegen to generate the proxy classes instead of manually coding it.
See also: RAML
There is an RSDL (restful service description language) which is equivalent to WSDL. The URL below describes its practice http://en.wikipedia.org/wiki/HATEOAS and http://en.wikipedia.org/wiki/RSDL.
The problem is that we have lots of tool to generate code from wsdl to java, or reverse.
But I didn't find any tool to generate code from RSDL.
WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate
However, REST uses the network protocol by using HTTP verbs and the URI to represent an objects state.
WSDLs tell you at this place, if you send this message, you'll perform this action and get this format back as a result.
In REST, if I wanted to create a new profile I would use the verb POST with a JSON body or http server variables describing my profile to the URL /profile
POST should return a server-side generated ID, using the status code 201 CREATED and the header Location: *new_profile_id* (for example 12345)
I can then perform updates changing the state of /profile/12345 using the HTTP verb POST, say to change my email addresss or phone number. Obviously changing the state of the remote object.
GET would return the current status of the /profile/12345
PUT is usually used for client-side generated ID
DELETE, obvious
HEAD, gets the status without returning the body.
With REST it should be self-documenting through a well designed API and thus easier to use.
This is a great article on REST. It really help me understand it too.
WSDL 2.0 specification has added support for REST web services too. Best of both worlds scenario. Problem is WSDL 2.0 is not widely supported by most tools out there yet. WSDL 2.0 is W3C recommended, WSDL1.1 is not W3C recommended but widely supported by tools and developers.
Ref:
http://www.ibm.com/developerworks/library/ws-restwsdl/
The Web Application Description Language (WADL) is an XML vocabulary used to describe RESTful web services.
As with WSDL, a generic client can load a WADL file and be immediately equipped to access the full functionality of the corresponding web service.
Since RESTful services have simpler interfaces, WADL is not nearly as necessary to these services as WSDL is to RPC-style SOAP services.
I mean, really, what is the point of SOAP?
Web services have been around for a while, and for a while it seemed that the terms 'SOAP' and 'Web service' were largely interchangeable. However SOAP always seemed unwieldy and massively overcomplicated to me.
Then REST came along, and suddenly web services made sense.
As Joel Spolsky says, give a programmer a REST URL, and they can start playing with the service right away, figuring it out.
SOAP is obfuscated behind WSDLs and massively verbose XML, and despite being web based, you can't do anything as simple as access a SOAP service with a web browser.
So the essence of my question is:
Are there any good reasons to ever choose SOAP over REST?
Are you working with SOAP now? Would it be better if the interface was REST?
Am I wrong?
As Joel Spolsky says, give a programmer a REST URL, and they can start playing with the service right away, figuring it out.
Whereas if the service had a well specified, machine readable contract, then the programmer wouldn't have to waste any time figuring it out.
(not that WSDL/SOAP is necessarily an example of good implementation of a well specified contract, but that was the point of WSDL)
Originally, SOAP was a simple protocol which allowed you to add a header to a message, and had a standardized mapping of object instances to XML structures. Putting the handling metadata in the message simplified the client code, and meant you could very simply persist and queue messages.
I never needed the header processing details when I built SOAP services back in 2001. This was pre-WSDL, and it was then normal to use GET for getting information and queries (no different to most applications which claim to be REST; REST has more in terms of using hyperlinks for service discovery) and POST with a SOAP payload to perform actions. Those actions which created resources would return the URL of the created resource to the client, and the client could then GET the resource. I think it's the fact that WSDL made it easy to think only in terms of RPC rather than actions which create resources which made SOAP lose the plot.
The way I see it, SOAP might be more "flexible", but as a result it's just way too complicated (you mentioned the WSDL, which is always a stumbling block to me personally).
I get REST. It's simple. The only downside I might see is that you are limiting yourself to those 4 basic actions against a single resource, which might not exactly fit the way you view your data.
The topic is well-discussed in Why is soap considered to be thick.
While doing some research to understand some of the answers here (especially John Saunders') I found this post http://harmful.cat-v.org/software/xml/soap/simple
SOAP is more insane than I thought...
The point of WSDL was auto-discovery. The idea was that you wouldn't have to write client code, it would be auto-generated.
BTW. next step beyond WSDL are Semantic Web Services.
If you don't need the features of the WS-* series of protocols; if you don't need self-describing services; if your service cannot be completely described as resources, as defined by the HTTP protocol; if you don't like having to author XML for every interaction with the service, and parse it afterwards; then you need SOAP.
Otherwise, sure, use REST.
There's been some question about the value of a self-describing service. My imagination fails me when it comes to imagining how anyone could fail to understand this. That's on me. Still, I have to think that anyone who has ever used a service much more complicated than "Hello, world" would know why it is valuable to have someone else write the code that accepts parameters, creates the XML to send to the service, sends it, receives the response, then turns that back into objects.
Now, I suppose this might not be necessary when using a RESTful service; at least not with a RESTful service that does not process complex objects. Even with a relatively simple service like http://www.earthtools.org/webservices.htm (which I've used as an example of calling a RESTful service), one benefits from understanding the structure of the returned data. Even the above service provides an XML Schema - it unfortunately doesn't describe the entire response. Given that schema one still has to manually process the XML, or else use a tool to produce serializable classes from the schema.
All of this happens for you when the service is described in a WSDL, and you use a tool like "Add Service Reference" in Visual Studio, or the svcutil.exe program, or I-forget-what-the-command-is-in-Eclipse.
If you want examples, start with the EarthTools services, and go on to any other services with more complicated messaging.
BTW, another thing that requires self-description is description of the messaging patterns and protocols supported by the service. Perhaps that's not required when the only choices are HTTP verbs over HTTP or HTTPS. Life gets more complicated if you're using WS-Security and friends.
I find that SOAP fits in most appropriately when there is a high probability that a service will be consumed by corporate off the shelf (COTS) software. Because of the well specified contract employed by SOAP/WSDL most COTS packages have built in functionality for consuming such services. This can make it easy for BPM/workflow tools etc. to simply consume defined services without customization. Beyond that service use case REST tends to be my goto web service implementation for applications.
Well it appears now that the WSI agree that SOAP no longer has a point as they have announced they will cease to exist as an independent entity.
Interesting article about the announcement and some commentary here: http://blogs.computerworlduk.com/simon-says/2010/11/the-end-of-the-road-for-web-services/index.htm
Edited to be completely accurate in response to John Saunders.
I think SOAP appeals to the Java and .net crowd who may be more familiar with the old CORBA and COM and less familiar with internet technologies.
REST also has one major drawback: there is very little guidance on how to actually implement such a system. You will find significant variations on how many of the public RESTful APIs have been designed. In fact many violate key aspects of REST (such as using GET for manipulation or POST for retrieval) and there are disagreements over fundamental usage (POST/GET vs POST/GET/PUT/DELETE).
Am I wrong?
"You're not wrong, Walter, you're just... :)"
Are there any good reasons to ever choose SOAP over REST?
SOAP, to my understanding adheres to a contract, thus can be type checked.
SOAP is a lightweight XML based structured protocol specification to be used in the implementation of services . It is used for exchanging
structured information in a decentralized, distributed environment. SOAP uses XML technologies for exchanging of information over any transport layer protocol.
It is independent of any particular programming model and other implementation specific semantics. Learn More about XML
SOAP Messaging Framework
XML-based messaging framework that is
1) Extensible : Simplicity remains one of SOAP's primary design goals. SOAP defines a communication framework that allows for features such as security, routing, and
reliability to be added later as layered extensions
2) Inter operable : SOAP can be used over any transport protocol such as TCP, HTTP, SMTP. SOAP provides an explicit binding today for HTTP.
3) Independent : SOAP allows for any programming model and is not tied to Remote procedure call(RPC). SOAP defines a model for processing individual, one-way messages.
SOAP also allows for any number of message exchange patterns (MEPs) .Learn more about SOAP