What RESTful actually means
codewords.recurse.com
codewords.recurse.com
I like how Dropbox bucked the trend and went with a simple POST based API. JSON parameters in. JSON response out. No complicated urls, strange headers, verbs, hateoas, etc..
https://www.dropbox.com/developers/documentation/http/docume...
There are people who understand it to varying degrees. Some who completely understand it and some who don't understand it at all.
So no, it's not a buzzword, it's just a concept.
PS. Dropbox's API requires a lot of hardcoding because of that very switch. Hardcoding that HATEOAS lets you avoid.
Because it is not a well defined protocol, you cannot use the same client library to access random REST APIs. You use/write one library to access Twitter's REST and another to access Facebook's REST. You could argue that you use HTTP in both cases, but that's just the underlying transport protocol - not the API "language" itself. Because of that fact I blame REST for the millions of developers hours wasted in re-implementations of hundreds and thousands versions of the same "concept".
The REST "idea" sure looks sexy when you put it next to an atrocity like SOAP, but that's one of its very few merits.
You misunderstand what REST is. It's not a protocol, it's an architectural style. Of course you can't build one client library to access arbitrary REST APIs – that's like complaining that you can't build an object-oriented library that can be used by any object-oriented language.
REST does, in fact, have a precise definition that is possible to understand and agree on. It's here:
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
I think REST is quite clearly a buzzword. That doesn't mean it's not also a well defined concept; just that it's fashionable to use the term even when that concept doesn't apply very well.
I've had the "pleasure" of working with big European consortiums where REST is very much a buzzword. I quickly realized that people were using the term as a synonym for "HTTP" for the purpose of making grant proposals and deliverable reports sexier. It's definitely a buzzword!
REST APIs are nice because they follow the data model so closely but there are so many cases in which I am trying to overload something to bend the pattern to my needs. Then again, Stripe seems to have created a fantastic API that handles many complicated cases so maybe it just requires more upfront thought - https://stripe.com/docs/api.
I disagree that REST is a buzzword, though. I think that REST has become so popular because it's a very effective way to construct an API.
afterthought: There are plenty of "RESTful" APIs that miss the mark on important concepts in the pattern. In this case, I would say - yes REST is worthy of the term buzzword.
Imagine if Dropbox registered a set of mime-types for each of the different resource representations. Those mime-type RFCs would describe how clients interpret the representations whilst simutainiously giving Dropbox the ability to change the server as they need without fear of breaking clients.
This would be because clients would be foxing on how to process the media-types, not the API. The various interactions a client can make with a representation (regardless of the URL it came from) would be bound to the media-type e.g. rel-types for edit, upload, create etc which the RFC would describe the appropriate HTTP interactions e.g. POST a media-type of x to the url at rel-type "edit".
However, I think the real reason that REST hasn't been adopted fully is that service providers like Dropbox have found that there advantages to binding client developers to their hardcoded APIs; the last thing Dropbox wants (and what REST would provide) is a standardised set of media-types and RFCs describing the interactions for a standardised way of interacting with an external cloud-based storage provider.
It's just another form of lock-in, and reminded the cynic in me of the bad old days of MS Office document lock-in.
When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities. REST or not building a client for one doesn't really make you closer to using another. Also Dropbox's old API was REST and it doesn't seem more portable (https://www.dropbox.com/developers-v1/core/docs)
The way a client interacts with the server is via the media-type and HATEOAS (via the rel-types).
If Dropbox's API was RESTful, you'd be able to use Google by only switching the initial URL - which could even be configurable by the user, or auto-discovered from the website.
When you start playing with the APIs from lots of different cloud storage folks (Dropbox, OneDrive, Google Drive) you see that they vary widely in concepts and capabilities.
They don't vary _widely_ in concepts and capabilities, they add a layer on top of the same concepts (files, directories, upload/download, get public URL), and REST allows you to support generic and specific clients easily, by either using extensible or multiple media types.
Also Dropbox's old API was REST and it doesn't seem more portable
It resembled REST, but it wasn't. A good way to tell: if you need a documentation page with a list of all the URLs you can call, it's probably not RESTful.
You really don't think that a flexible client which is able to discover resources and actions based only on an initial URL is more complex than one which is more hardcoded to a specific implementation and resources? I must be missing something, because to me, it obviously is.
The obvious example of the Web and web browsers is not entirely convincing to me. Yes, browsers are flexible, but at the same time, the Web is an incredibly specific example. There are "hardcoded" expectations of what a web browser must be able to do, that I simply don't see in more general examples and use cases. And whenever we want to do something out of the ordinary with a web browser (I know, I know, "web browsers were never meant for that!") this general model of the web breaks down and we stray into wildly incompatible and hacky ways of doing things.
When the conditions are right, you do see this: RSS/Atom is a good example.
Show me a general purpose program that can navigate, interpret and comprehend a variety of media types and I will show you an AI.
But what I really see as the main advantage is the decoupling of server and UI, kind of like Android Intents on steroids. By using standard formats and dynamic routes between them, the user is no longer tied to a silo with a window through which they can interact with their data; they can know use his own chosen software to handle the different types of information, jumping through them as needed, without ever being locked-in to a particular provider.
And for the developers, why are we building the same crap again and again using the API du-jure, when 90% of it uses the same concepts as existing software? Why do we need thousands of libraries and middleware that provides a "single API to many services"? We spend so much effort building these rickety integrations, just because the providers insist on using different names for the same things.
Doesn't it abhor you, the waste of it all?
I agree that the current situation is crappy. I agree that HATEOAS/REST ideas implemented properly and with the intend to cooperate would help a lot, and that there are many worse candidates for a standard.
I disagree that HATEOAS/REST would matter that much, compared to the "implemented properly and with the intend to cooperate".
Also the existence of WebDAV doesn't really demonstrate that merely adhering to REST will make your clients portable.
It's been a while since I've worked with it, but IIRC, WebDAV is one example.
> Dropbox's old API was REST
That's not REST. It's that weird anti-REST where people define URI patterns instead of media types. I don't know why it became trendy to label things like that REST, but they aren't.
WebDAV? You can get pretty far with eg davfs and Plone/Zope -- and you can also mix and match servers and clients. Now, lots of WebDAV clients and servers are broken in many sad ways... but it exists.
Fielding worked at Day Software, which made a web content management system. They contributed parts of their system to the community as Apache Jackrabbit [1] before getting acquired by Adobe.
Not sure if Day Software's APIs match your asks though.
I'd argue it's not a problem if a vendor can generate clients for his API.
I'd also argue that most clients break with each API version anyway, because of the way developers code them.
State is carried by the client, the client traverses links to find out what it can do, the responses are described by a published content type, and the content type defines the semantics of the protocol.
It's not hard, but people like to pretend that it is. Nothing says you can't stick to GET and POST, nothing requires weird headers.
"ReST in Practice" is a great introduction for engineers.
Facebook, Amazon, and Hacker News are good examples of RESTful applications. You can enter them through their website roots with no prior knowledge beyond standard web media types like HTML/CSS. The site roots display some information, expose some functionality like search, and link to pages with more capabilities like to create an account. The search function is expressed as an HTML form, and when the user submits their search, the HTML spec tells the browser to navigate to a new URL composed from the search form fields. The search result page displays a list of hyperlinks to other resources, such as products on Amazon or people on Facebook. Navigating to those pages lets you discover information and hyperlinks to other resources such as a person's photos, related products, etc.
The way a browser navigates through a website by following links is the classic example of a RESTful application, and is the meaning of "hypermedia as the engine of application state". Fielding also wrote a blog post clarifying REST and its constraints: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
> A REST API should be entered with no prior knowledge beyond the initial URI and set of standardized media types that are appropriate for the intended audience. A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). A REST API should never have “typed” resources that are significant to the client. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type
Some confusion about REST seems to stem from misguided attempts to apply REST to scenarios for which it's not a good fit - scenarios where there is by necessity tight coupling in the form of mutual knowledge of specific data types and operations. Other confusion about the term "REST" comes from applying subset of its principles, resulting in a popular label that refers to a large spectrum of architectural styles. The Richardson Maturity Model helps organize these functionality subsets into levels that can be named and considered separately - services termed REST are sometimes level 1 or 2 in the Richardson model.
http://martinfowler.com/articles/richardsonMaturityModel.htm...
An API is probably the worst thing to try to make truly RESTful, in the full HATEOAS sense.
Further confusion comes from the fact that some of the REST constraints are actually very useful in machine-to-machine API design. Thinking about a system in terms of a large number of resources operated on by a standard set of verbs is nice. Caching is nice. The un-bloating of HTTP bodies from the SOAP days is nice.
I think there is some consensus that we can call that thing an "HTTP API" rather than a "REST API", which might start to clear up some of the confusion.
With the web, it is not the browser doing the navigation; It is very advanced AI wetware.
It is hard to find widespread examples of machine to machine interaction based purely on RESTful discovery.
I think REST is interesting - but at the end of the day, is it really all that different from other communication mechanisms?
Why does it drive you nuts?
REST as a concept was created as a way of characterizing a successful architectural style seen in web applications, a common set of constraints and advantages realized from those constraints. REST is attempting to characterize the architecture of the web, so I think it would be accurate to say "the web itself is RESTful":
> The first three chapters of this dissertation define a framework for understanding software architecture via architectural styles, revealing how styles can be used to guide the architectural design of network-based application software. Common architectural styles are surveyed and classified according to the architectural properties they induce when applied to an architecture for network-based hypermedia. This classification is used to identify a set of architectural constraints that could be used to improve the architecture of the early World Wide Web.
> Architecting the Web requires an understanding of its requirements, as we shall discuss in Chapter 4. The Web is intended to be an Internet-scale distributed hypermedia system, which means considerably more than just geographical dispersion. The Internet is about interconnecting information networks across organizational boundaries. Suppliers of information services must be able to cope with the demands of anarchic scalability and the independent deployment of software components. Distributed hypermedia provides a uniform means of accessing services through the embedding of action controls within the presentation of information retrieved from remote sites. An architecture for the Web must therefore be designed with the context of communicating large-grain data objects across high-latency networks and multiple trust boundaries.
> Chapter 5 introduces and elaborates the Representational State Transfer (REST) architectural style for distributed hypermedia systems. 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. [...]
> Over the past six years, the REST architectural style has been used to guide the design and development of the architecture for the modern Web, as presented in Chapter 6. This work was done in conjunction with my authoring of the Internet standards for the Hypertext Transfer Protocol (HTTP) and Uniform Resource Identifiers (URI), the two specifications that define the generic interface used by all component interactions on the Web.
(To be clear, I'm not intending to comment on whether REST is good or bad, nor its suitability to a purpose like API design. I just mean to comment on what it factually is and is intended to be, since from my perspective it frequently seems to be misunderstood.)
[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/introduc...
Fielding's REST requires that the protocol be "stateless"... not that there be no state, but that the client and the server need not keep track of each other. Cookies, as Fielding explicitly calls out, are in violation of this principle. Every website that uses cookies is not RESTful.
Some people might conclude from this that FB, Amazon, and HN are "not good", because they're not RESTful. I personally conclude something else, but YMMV.
Also deciding to put the session ID in a cookie not the URL is purely a pragmatic approach (e.g for security reasons).
It's still possible to use sessions and other ways of maintaining client state while adhering to other stateless principles such as indempotency of certains types of requests.
I've built hypertext APIs, and they worked really well.
We had a(n overly) complex domain model where most of the complexity was around managing a permissions model for access to resources. We tried a whole bunch of ways to represent the actions available to end users, but the only one that worked really well was to advertise a URI when you could do something, and to omit it when you couldn't.
All the nightmarish logic was safely hidden behind the uniform interface. Clients only needed to know that they should follow links, and that the absence of a link meant that a resource wasn't available to them because reasons. It was a beautifully natural mapping of a difficult problem domain into a simple consumption model.
As a bonus, we could change URI structures around when we felt like it, and our clients never missed a beat, because they always followed links from a well-known entry point.
It's not always the right choice, there is plenty of room for simple RPC, but for workflows, and dynamic discovery of resources ReST works a treat.
And haven't this people been right? :)
It was (and still is, but people are fortunately more skeptic) completely oversold like REST now.
In my experience hiding the existence of a network behind several layers of abstraction is a really bad idea.
As I remember REST was popularized by Rails a few years back. If you go back and look at the railsconf talk by Hansson in 2006 you can see that the Rails people just wanted something that handled CRUD operations. However, one of the drivers behind REST was to provide web services for machine to machine communication - something that was traditionally done by WSDL files in SOAP. The Rails people didn't really have much of a need for HATEOAS, because they were not interested in replacing WSDL files. Primarily they wanted to get away from the 800 pound gorilla that was SOAP services (that back in 2005 was what every Enterprise Java web app was doing). As a result the focus was primarily on PUT/GET/POST/DELETE.
I've seen a lot of "REST" API's that are actually HTTP/RPC API's or quasi-REST API's that mix REST for simple things, but then begin exposing RPC calls as the developers ability to manage complexity breaks down. I've never seen anyone actually using HATEOAS yet (maybe i've been isolated??)
Usually when your boss says "And it has to have a REST API!!" That means that 1. It must use the internet, 2. It must return JSON, 3. It uses URLs to do things. Basically if the above is true it's a RESTful API. I think that most developers actually believe that are making a REST API even when they are not - simply because they don't really know.
Your right about being the new XML buzzword though. 10 years ago if you did web services having WSDL, XSTL, SOAP and XML on a resume meant you were the shiz. Today you have REST and AngularJS on your resume if you do web development. Meh :0
Github AFAIK
But at the end of the day, Dropbox is probably going to be just fine with their RPC API. So what gives? Why should Dropbox care about REST? How would you sell the CEO on it?
I'd love to read a follow up blog post called "What does REST buy you anyway". Related: https://xkcd.com/1270/
Twilio Conference 2011: Steve Klabnik, Everything You Know About REST Is Wrong: http://vimeo.com/30764565
REST APIs must be hypertext-driven: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
Hypermedia APIs - Jon Moore: http://vimeo.com/20781278
Designing a RESTful Web API: http://blog.luisrei.com/articles/rest.html
I'm sure you can find 50 developers that will disagree on your definition and that's what hurts all the REST advocates. Your definition is as valid as theirs, until there is a spec that explains precisely what REST is. There is none, there is no normative spec, period.
SOAP has a spec, RPC has a spec, GraphQL has a spec. "REST"(full) has no spec, REST is whatever you think it is.
> There is none
You can't build a standard REST client since there is no spec, but you can build a libraries that mostly work, since you can identify the pattern quickly.
IIRC, in an article by Roy Fielding that I read, he said that REST is an architectural style.
Nonsense. REST is what Dr. Fielding says it is, because he coined the term.
And if REST isn't practical, we should use a different term to describe what we implement instead.
The meanings of words should be immutable, to avoid confusion. No, that's not how language has historically worked, but we can do better. After all, there are a lot of things we have historically done that we don't want to keep doing.
It's spelled ReST.
Does that better convey what it means in that string of characters? Maybe for some values of human. But words are for humans, and humans are not immutable, so our words shouldn't be.
Really? It's been capitalized REST everywhere I've seen it.
Including here: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch...
You weren't thinking of 'reST' (reStructuredText) were you?
What I was responding to was advocacy that human language should behave the way we expect RFCs to work.
Since when has language historically worked that way? Ever wonder why we have words with 7 officially accepted definitions? Because usage and interpretation changes with time. Perhaps you're confusing language and mathematics?
If Stripe, e.g., were to build a truly REST machine-to-machine API then they wouldn't need to create any documentation of "endpoints". Developers would only need to point a generic REST client at the API's root URL and all the other endpoints would be discoverable from there.
This is impractical, because a machine-to-machine API will generally know that it wants to charge a credit card or update a billing address and will reap benefits of knowing exactly how to do that without the overhead of going to the root of the API and navigating the resource tree every time.
It can be summed up like this: pure REST is practical in situations where tight-coupling of a client and server's interactions is undesireable. In machine-to-machine interactions, there is almost always some value in tight coupling, or at least a level of coupling that pulls the system away from being "pure" REST. Hence it's rather impractical.
REST is literally a backwards description of the web and browsers as we know it, so yeah, what are you talking about?
Section 6.3 is even about which parts of HTTP are RESTful or not http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluatio...
Chronologically speaking, REST is an attempt to fit the relatively-organic growth of the web into a systematized conceptual framework, and a totally untested theory about how it succeeds.
On the first count, it obviously is incorrect. You even pointed out that Fielding points this out! Any part of the web that uses cookies is not RESTful! So REST is not something that "describes the web", it describes an idealized version of the web that in fact has only a tiny fraction of the functionality that the actual web has.
On the second, as far as I'm aware, there is absolutely no evidence supporting Fielding's claims about the relationship between the properties of REST and the success of the web. We may or may not find his points persuasive (I do find his points somewhat persuasive), but please remember that this is someone's thesis, in every sense of that word.
Yes, and be to accurate,I'm talking of what people call a RESTful architecture in software development.
REST (http://www.ics.uci.edu/%7Efielding/pubs/dissertation/rest_ar...)
HTTP REST (http://cafe.elharo.com/web/why-rest-failed/)
GET/POST vs GET/POST/DELETE/PUT (HTTP REST) (http://www.artima.com/lejava/articles/why_put_and_delete.htm...)
A more recent look at GET/POST over HTTP REST (http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post)
I'd argue that JSON-RPC (as well as XML-RPC) is more useful than REST, as it has a simple specification that any client/server could follow. If you write a JSON-RPC server, you can expect that any JSON-RPC client would be able to use it.
I've designed and operated several REST-inspired systems over the years, and let me warn you: it's no walk in the park. Engineers that want to "get it done now" must be convinced not to huck everything up to the server as a POST. Founders have to see the business case for every new system. Other departments may have to relearn tools for interoperating with the systems. It's a whole big deal. You can't deploy a RESTful solution and avoid dealing with people.
For your effort, you'll receive a system with well-factored bounded contexts whose self-descriptive interfaces interoperate with standardized tooling and monitoring systems. Projects can be factored into tasks along clear domains and often incrementally delivered into production. Life-sucking productivity projects like the secret admin website can be pushed off indefinitely. Problems will be simple to isolate and reproduce. You'll have the flexibility to rush out brand new client experiences on tight deadlines.
Notice how none of the problems or benefits really involve a particular technology tool or framework or language?
In my opinion, ignorance of the significant cultural factors required for a successful deployment of a RESTful system is the reason why articles continue to be published about how it's vague or difficult or whatever.
- HATEOAS - registered mime-types
In particular, the use of registered mime-types. An example:
Say we are building a restful music service similar to Spotify. Say we focus on the list of as users playlists. We can embody the currently logged in users list of playlists as a resource with a specific URL. This URL is opaque to both the client and server.
The representation of this list of playlists could be in the form of a Json hash where key is the playlist name and the value is the URL for the playlist itself.
We also could declare that the following interactions are available to any client that receives this payload from a HTTP GET request: - Create a new playlist - delete a playlist And therefore we can fulfil the HATEOAS requirement.
As I understand it, in order to make this restful we must register this as a custome media type as the additional actions we have defined are part of the available interactions with this media-type.
Don't confuse the content of the representation with a definition of a media-type; we could declare our custom media-type as so:
Application/vnd.spotify.com.list.playlists+Json
It is the definition of the media type that dictates that the HATEOAS links in the header with the rel type of create or delete of how clients should interpret them. It is this media-type that dictates this.
It is my understanding that pumping raw Json over http, even with HATEOAS in the headers (or even worse, with links embedded in the Json with the out of band knowledge that a client should interpret our key/value pairs as hypertext based only on the resource URL) is not in anyway restful.
It is akin to to functional programming or declarative database queries. Neither of these are large-scale patterns.
They're both very much about a sane, easy to understand api.
For this reason, I've always thought that the term "stateless" is confusing. Maybe "client state independent" (the response that the server sends back is independent of the client's state)? I don't love that term, any better ideas?
As simple as that.
None of this requires state on the server.
I need to store a state somewhere at least. That’s not really stateless.
I'm not really convinced that's not a good idea for a TLS-only service (compared to the complexities that tokens/cookies introduce). One reason why there was a move away from Basic Auth was ofcourse that it is crazy to send plain-text login/password pairs over a plain-text transport (HTTP sans S).
And there's never been any working, cross-platform effort to improve things (AFAIK).
There's some work on Kerberos that's interesting, but again, many of these efforts have been simply co-opted by the fact that everyone used cookies (and had problems, and started encrypting them etc), and then moved from HTTP to HTTPS.
When you have HTTPS, there's not that many reasons to not just have "SECRET PASSWORD" in the URL (granted that'd not be REST either, but BASIC AUTH does the same thing, just in a header).
If you have to do a challenge-response auth every 5 requests, or so, to get a session, then it’s not really rest.
Client certificates might actually make the most sense in this case.
A good read: https://www.safaribooksonline.com/library/view/restful-web-s...
The "simple" answer is to have client-certificates, and allow a client access directly to an application server over TLS, or use a secure transport (eg: IPSec), and just use standard HTTP auth on every pass (which AFAIK never was extended to use some form of standardized token, so one's left with sending the actual login/password pair every time).
The sane compromise is to just use encrypted cookies -- but they are also bolt on solutions.
The problem is that essentially one needs encryption to ensure secure sessions, which essentially boil down to authenticating the client to the server, and the server to the client, and forming some kind of session (typically DH for a symmetric session key).
For a long while, encryption was really expensive compared to the db lookup and template render that "every" web application did -- and so we've ended up with a mess of "best practices" which aren't very good at all (and not a very good way of moving from REST-that-trusts-plaintext-ip to REST-and-also-secure).
With HTTP/2 it looks like things are moving towards making the transport-protocol part do the things it should -- track the session, and secure the session. Still doesn't do a good job of authenticating the client in any meaningful way, but it should simplify some of the assumptions that are necessary to build a secure(ish) system.
But if there are any here who are strong advocates, I truly want to know, how do we authenticate in a REST compliment way in practice? Must we, as was pushed early on, only use HTTP basic auth, and resend credentials with each request? Or do we treat the session itself as resource, and somehow refernce it in requests for all other resources? Or are session cookies somehow exempt from the rule that interactions must be stateless?
HTTP basic auth does this automatically.
Creating a resource for a session is optional but may be useful if the state to sent back and forth is too big. But this will require centralized storage.
The state may be stored inside a cookie where parts of it can be encrypted. It is also possible to specify that parts can only be updated by the server.
You may also use Local Storage and send the data across using an XMLHttpRequest or even use a HTML form (which may have limited support for the HTTP verbs).
Read my other comment for more information.
The server is stateless because it receives the latest state from the client (location, cookie and other headers) and sends an new updated state (location, set-cookie and other headers) to the client again along with an optional representation. There is no need for the server to keep the state in memory anymore. Because the server does not keep the state it does not matter which copy of the server (in case of load-balancing or fail-over etc.) handles the next request as everything needed can be derived from the state sent along with request from the client.
Keep in mind that it is best practice to be able to reproduce a representation by the use of a resource identifier, like with "pure functions" in functional programming, it should be deterministic. The content of a representation may change but not the semantics of it.
The part that is stateful is the state that is being passed back and forth between the client and the server.
Does that answer your question?
https://medium.com/@vrashabhirde/will-the-real-restful-api-p...
(edited again to make it less rant-y and offensive and more useful)
It's very complicated and follows the pattern very closely.
From my experience, I would suggest something like Twilio, Github or FoxyCart as the epitome of a REST API.
Still, GitHub is a far more complete RESTful example than most.
Wikipedia might be another not-quite-but-pretty-close example.
REST came about as a formal description of the architectural patterns that made the WWW a success.
I always thought it was just a way of sending commands or data to a sever. I created a RESTful (I think) service on a Raspberry Pi that powered on a light every time it got an alert from Salesforce. It did this by POSTing to power.py and parsing in some variables. Is that RESTful?
> ELI5 for a non-developer?
In chapter 5, he describes a particular set of properties, for a particular family of architectures, and calls them "REST".
Years later, a whole ton of people misunderstand all this and call all sorts of other things REST.
Confusion abounds.
Imagine we want to change the state of light 7 (and only light 7).
A PUT/PATCH of "ON" "OFF" (or 1 or 0 or a float for a dimmer) to http://raspberry1.local/lights/7 to change the status of light 7 is better IMO than doing a GET to http://raspberry1.local/lights and then a PUTS/PATCH to that same URL to update all lights status for the purpose of just updating one light. The latter is obviously fragile in the face of multiple writers (you'll lose updates on overlapping but not colliding writes-an update to light 6 that overlaps in time with light 7 can result in the earlier of those updates being lost when there's no inherent reason for it).
ie
PATCH http://bla/url/lights
{ light1: ON, light351: ON, light 4672: ON }
I think that since generally documentation around RESTful API's is generally very good with in-browser demo calls, interpretation of the REST API although differs between implementors, is generally relatively similar enough.
However there are cases where REST design just won't work, or implementing the design abstracts work from the API supplier to the consumer. Where once a "runThisScript(object)" would be easy enough for a developer, now the script itself must be implemented by the developer to call the RESTful endpoints.
In cases like this, we occasionally break REST design for the convenience of developers.
so: /lights /lights/light-id /lights/light-id/wattage (return wattage of light)
Doing something like:
/lights/light-id/book-janitor-to-replace which might email and update the janitor's calendar/ToDo list, isn't really following the existing API design.
A good API imo would hide the janitor's calendar/ToDo list unless it was absolutely necessary for the client to access it directly. Then an argument could be made in favor of the booking janitor endpoint on a light - and the API is no less RESTful.
Edit: I don't like it when people over-emphasize resources when talking about REST. I blame this practice on Rails being many people's first introduction to REST. But Rails isn't actually RESTful per Fielding. I prefer to use the term resourceful API to describe the kind of API Rails prescribes. REST is generally in favor of custom endpoints that hide complexity from the client, even at the expense of having a clear cut decision on eg. POST vs PUT/PATCH for a given endpoint.
Recursion can be done by the use of nested "resource identifiers" (SSI or ESI for example) inside the returned "representation". A "connector" may then decide to do another request to replace the "identifier". If the "connector" uses caching it may not even need to do another sub-request. I use this to do something like what Facebook's Relay does. As the full state is always being sent along with every request it is very easy to scale because the servers, wherever they are, always have enough context to be able to work with it. A server may even ignore what it does not understand for the next layer to handle it called "partial understanding" which is supported by XML for example. Unfortunately when using JSON most of these advantages are lost. That is why I prefer a less verbose "XML Infoset" similar to JSON while still keeping all the advantages.
http://www.cc.gatech.edu/~keith/classes/ubicomplexity/pdfs/i...
The whole RPC vs. REST thing is not a useful distinction.
I know there's a few set of rules/principles to follow but in the end, I just see "lets make a readable and easy-to-understand API that has a nice set of plural "subjects" with the basic HTTP request verbs all nicely applied.
I ask this because I noticed while applying for jobs, that some people hiring simply want someone who can write a REST API but I just didn't see it as a big deal when you're hiring a web developer as long as he has the experience and good mentality for creating organized code.
I would probably say...
""" REST, like many great religious philosophies, combines with one's life experience to mean something different for every pair of eyes that looks at it. For me, it's something which has URLs for resources of the form
/<class_name>(/<instance_id>(/<custom_method>)?)?
You will notice the repetition of sets of 3, and that's because 3 is my favorite number. I also really like the Stripe API's way of specifying arrows to related content to "unfold" references in the JSON response. That really puts my mind at rest when I see it, so that's RESTful, as well.
To get a little more real, though, REST is totally the old hotness and verging on not even being that hot. All the cool kids now know to use GraphQL, and if you aren't at least planning to transition to it, I'm not really interested in working here unless you pay me a lot of money. """
How'd I do?
But having said that I've got the point where I don't really care - if I can interact with an API from curl without too much difficulty I don't care if the API is fully REST or not.
It's literally a backwards explanation of the web and browsers.
workitout's response is less tongue-in-cheek, if you prefer that: https://news.ycombinator.com/item?id=10767440
I mean, statistically speaking, if you have such a system, my bet is that you call that system RESTful. Furthermore, if you have such a system, you vastly outnumber the people building systems that obey Fielding's constraints. So in practice, you win the argument about what "RESTful" means.
Can we please stop legitimizing Rails's whimsical aesthetic choices by pretending that they have something to do with an academically-justified architecture, and just accept that they're just another way of ripping your denim and then safety-pinning it closed, by which you demonstrate that you're not a square and you don't write Java.
What's wrong with calling it an HTTP API?
Please don't. Snark like this is good for starting technical flamewars but it invariably lowers the quality of the discussion.
"3.4.7 Remote Data Access (RDA)
The remote data access style [131] is a variant of client-server that spreads the application state across both client and server. A client sends a database query in a standard format, such as SQL, to a remote server. The server allocates a workspace and performs the query, which may result in a very large data set. The client can then make further operations upon the result set (such as table joins) or retrieve the result one piece at a time. The client must know about the data structure of the service to build structure-dependent queries."
http://www.ics.uci.edu/~fielding/pubs/dissertation/net_arch_...
REST is a very specific architecture, with very specific constraints. Not everything is REST, not everything should be REST. And there's certainly no reason to call things REST, if what one means is simply a client-server application over HTTP. But if what one is building is "just" client-server, perhaps HTTP isn't the best transport.