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 8 years ago.
Improve this question
There has been a lot of hype over REST last few years, and I've tried to embrace the principle and understand it's benefits. Some things about REST still elude me, though. I'll try to be concise and to the point:
Can a web application be considered RESTful? What are the benefits of this? I can understand (to a point) advantages of RESTful service, which is to be used by many clients, but what is gained by using REST principles when developing application interface which is to be consumed by HTML/JS frontend?
REST mandates use of verbs which roughly map to CRUD operations and to which the server responds with representations which in turn put client in a new state. Does this imply that ALL actions on a resource must be done through modification/creation/deletion of that and possibly many other related resources? What about "atomicity" of such operations (i.e. transactions)?
REST compliant service is supposed to be self-descriptive (through HATEOAS principle), but the lack of metadata makes it impossible for a client to e.g. create a resource without knowing exactly what fields (and their types) are mandatory. This information must still be provided out-of-band. Is there something I'm missing here?
I could come up with more questions, but it will be enough for now if someone could clarify these points for me.
Some notes about your questions:
1) If your web application is a Single Page Application the simplest way to communicate with the server will be if it is a Rest service.
For a traditional web application I think is better that "controllers" communicate with a service layer using dependency injection.
3) Yes, of course the client needs to know the format of the data it is receiving. But AFAIK, Rest does not give any constrain about how this metadata has to be defined or transmitted.
The HATEOAS principle refers more to the discovering of related resources from a given one.
There exists different conventions to express that relations, see for example:
http://stateless.co/hal_specification.html
2) Every Rest action must be atomic. If you need a some kind of long operation, the usual is to create a resource that describes the operation. The state of the operation is retrieved from that resource, and you do whatever you want with the operation (i.e. Cancel it) interacting with that resource.
See an example of that here.
1.Usually REST architecture is designed when application is going to be used by different
by nature clients(external api consumers, mobile applications etc). In this case development costs will be paid back completely.
Developing truly REST application is not such a simple task to do. So,
if you know in advance that your application is to be used only by your client-side, probably,
you could consider 100% RESTfull approach as an overhead. But it does not mean
that you should not design your application well, you still could use some of REST principles in your application.
For example, stateless application simplifies scaling, REST-style URLs looks good for users and search engines, etc.
2.Yes, in truly REST all interactions should be expressed via standard verbs on resources.
But you could still create Transaction resource to wrap around your transaction.
See great discussion here: Transactions in REST?
3.As I understand nothing prevent you from providing metadata-information in HATEOAS-based response.
Related
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 6 years ago.
Improve this question
Based on the articles I read, GraphQL is more resource-efficient in terms of roundtrips and it can also do what REST can provide. What are the reasons why software architect & developers might decide to stay with REST over GraphQL given that the web application will just be started from scratch? Also given that this is a continuous project, will be consumed from web and mobile and openID connect is a requirement.
This is a rather broad question but I'll try answer speaking from my own experience.
REST provides access to a specific resource, e.g. a user or a product. The result from a request will likely be an assumption of what data you will want or use, i.e. it's probably everything about that resource regardless of whether you use all the data or not.
There is also the problem of N+1. As an example, take the user has and belongs to many relationships scenario; with a RESTful API you would make a request to the user, e.g. /users/:id then make a request to all their relationships, e.g. /users/:id/relationships, so that's two requests already. There could be an assumption of the relationships endpoint to include both the relationship (friend, family member, etc.) and the user in the resulting array, but if the API doesn't make that assumption, you're going to have to make a request to each user endpoint to get the data on each user in each relationship.
This example can go deeper too; what if you want all second tier relationships (friends of friends for instance)?
GraphQL solves this by allowing you to ask for specifically what you need. You can construct a query to return the data at depth:
query myQuery($userId: ID!) {
user(id: $userID) {
id
name
relationships {
id
type
user {
id
name
relationships {
id
type
user {
id
name
}
}
}
}
}
}
Fragments could clean this up a bit and there may be recursive issues, but you should get the idea; one request gets you all the nested data you need.
If you don't have much need for such nested or inter-connected result sets, GraphQL may not offer much in a trade between benefit and complexity.
However, one of the greatest benefits I have found with GraphQL is its extensibility and self-documentation.
In my opinion, it is – among other aspects – also a question of use cases:
If you have something like an app or other frontend with a connection that is slow and/or has high latency (typical example: a mobile app), GraphQL’s “roundtrip minimisation” can be a big plus. And it can be pretty handy to give the client-side control over the data structure, thus often reducing the number of required API endpoints.
If it’s rather data exchange between servers, the fact that RESTful APIs are strongly related to HTTP, has advantages such as the semantics of verbs (which GraphQL cannot offer, as you perform several operations with one GraphQL query) and status codes. Plus: you get all the HTTP caching functionality for free, which can be really important in heavily data-driven applications/services. In addition, REST is ubiquitous (although probably most APIs advertised as “RESTful” aren’t, often due to missing support for hypermedia).
There might be multiple reasons. This is very subjective I believe, but to me it's based on:
REST is the old and steady way. It is used by the most and provides an easy interface to API consumers. Because it's old (by no means a bad thing) most developers know of it and know how to consume it.
GraphQL is the new guy in town. It sure does save some performance (roundtrips and payload) for most systems, but does change the way we think of a backend. Instead of providing resource endpoints, it provides the graph of the data model and let the consumer decide what data to get.
As of the point of the "new guy", GraphQL is not as battle tested. It is new to most and there fore not adopted by others and the first-movers and startups, basically.
But again, this is a subjective question with a subjective answer. Currently I am using GraphQL for a startup to test it's durability and see if it can solve our needs. So far, it does by far. If you are to make a decision on wether to start a new project with REST or GraphQL you should be consider your needs and how much money/time you want to spend learning new vs. doing what you know and get to your goal faster.
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 8 years ago.
Improve this question
If an API only allows retrieval of data (through GET) and does not allow Create, Update or Delete is it still RESTful?
I question this because Wikipedia says "When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource." as a constraint of REST.
I'm sorry if this seems like a silly question but I'm trying to get to the point where I can say 'I understand REST' confidently.
Yes, a system can use REST even if it doesn't allow modification of the resources.
The most common implementation and use of REST is HTTP 1.1 used for the world wide web (even if the RESTfulness is implemented vith varying success). A vast majority of the resources are read-only.
I believe that the API is still RESTful if even if it does not implement all of the verbs. This simply will not make sense for all resources. Some verbs may not apply, or a client may not be authorized to perform them.
Take for example newspaper articles. I could see that GET is the only available verb as the news site may only publish the API for reading (i.e. getting) the articles.
As for the Wikipedia definition, I would change that slightly to say "it has enough information to attempt to modify or delete the resource."
And the API can communicate support/non-support of certain verbs by response codes. If DELETE is not supported, a client DELETE request would see a HTTP 405 (not supported) response.
REST is not coupled to any particular protocol, so what methods are being used does not affect the RESTfulness of an API, as long as the methods are used for their standardized behavior and any deviations are documented. For instance, there's nothing preventing you from having a similar "read-only" API implemented over FTP, using the RETR method.
What really matters is how clients obtain the URIs for the resources they are retrieving. If they are using out of band information, like URI patterns in documentation, it's not RESTFUL. Resources should have links referencing each other and clients should be able to find anything they want starting from an initial entry point URI. Do some googling for HATEOAS if you have doubts on that.
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 6 years ago.
Improve this question
GitHub API is great. It's quite convenient and simple at the same time.
It fits REST style at first sight. But does it actually? And why, if not?
Just to review, REST has certain properties that a developer should follow in order to make it RESTful:
What is REST?
According to wikipedia:
The REST architectural style describes the following six constraints
applied to the architecture, while leaving the implementation of the
individual components free to design:
Client–server: Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable.
Stateless: The client–server communication is further constrained by no client context being stored on the server between requests.
Cacheable: Responses must, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing stale or inappropriate data in response to further requests.
Layered system: A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches.
Code on demand (optional): Servers can temporarily extend or customize the functionality of a client by the transfer of executable code.
Uniform interface: The uniform interface between clients and servers, discussed below, simplifies and decouples the architecture, which enables each part to evolve independently. (i.e. HTTP GET, POST, PUT, PATCH, DELETE)
Does the API have those characteristics?
So, with all of this said, looking at the table of contents of the Github API docs that you linked to, I see, "verbs" which satisfies the uniform interface requirement, "endpoint", its served over api.github.com which means its a layered system, it offers some json-p callbacks which would satisfy the "code on demand" part, there is an "authentication" mechanism before using any verbs therefore it is stateless, it is presumably cacheable since that is typical of this type of architecture, and with all of this, you already have most of the characteristics of a REST API.
Yes. its RESTful enough to be called a REST API.
github: /repos/:username/:repo
other: /users/:username/repos/:repo - refer to:http://www.slideshare.net/apigee/restful-api-design-second-edition
I think it is RESTful Style.
But why github use first style?
Maybe RESTful is no standard.
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.
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 6 years ago.
Improve this question
Along with half of the web developer community, I've been struggling to really and truly grok the REST style. More specifically, I've been trying to form some opinions on how practical a pure RESTful architecture really is between a web browser and an application server.
As part of my learning endeavor, I've been taking a look at some online examples of REST, specifically Twitter in this case. In their API documentation, they discuss their various "REST API Methods".
I'm struggling with rationalizing how exactly most of these are actually RESTful, beyond having a RESTful URL structure. Consider, for example, a simple GET request to http://twitter.com/favorites.
In a pure implementation of REST, I would expect identical requests to that URL, regardless of the initiating client, to return identical responses. In this particular case, though, we would obviously all see different responses depending on our currently authenticated users, which implies that our requests are being connected to some form of client state on the server before a response can be generated.
Hopefully that provides enough context for my question then - can that really be called "REST"? I get the impression that 90% of the so-called RESTful implementations between web browsers and application servers demonstrate this same inconsistency, where the restrictions on client state stored on the server are ignored.
Twitter breaks pretty much every REST constraint. Your example of http://twitter.com/favorites returning different results based on the authenticated user is an example of Twitter violating the "Resource Identification" constraint. Each interesting resource should have a unique identifier. My Twitter favorites and your Twitter favorites are two different resources and therefore should have two different URIs.
This actually is not related to idempotency at all. Idempotency is about being able to make the same request multiple times and it have the same effect. Even Twitter respects idempotency. If I GET my favorites multiple times, I still get my favorites back. How many times I do GET does not affect the result.
There are many other ways in which Twitter break the REST constraints. Many of these issues have been covered here on SO before.
Update
After perusing the Twitter api docs a bit more there is actually an alternative URI format that does properly identify the favourites resource. Here they show how to create an URL like:
http://api.twitter.com/1/favorites/bob.json
It still is a long way from being RESTful, but at least that's a step in the right direction.
In this context, idempotence is a tricky word. Even if you were retrieving an individual tweet, you would get a different result if that tweet were editable and someone edited it. When retrieving a list, I would certainly expect a tweet to retrieve the most current list.
It might be more helpful to think of idempotence as the ability to do something without causing side effects. So a GET is idempotent in this sense, but a POST is not.
From Wikipedia:
In computer science, the term
idempotent is used to describe methods
or subroutine calls that can safely be
called multiple times, as invoking the
procedure a single time or multiple
times has the same result; i.e., after
any number of method calls all
variables have the same value as they
did after the first call. Any method
or subroutine that has no side effects
is also idempotent.
Also from Wikipedia:
Methods PUT and DELETE are defined to
be idempotent, meaning that multiple
identical requests should have the
same effect as a single request.
In contrast, the POST method is not
necessarily idempotent, since
sending an identical POST request
multiple times may further affect
state or cause further side effects
(such as financial transactions [e.g. a customer getting mistakenly charged twice for the same product]).
See also:
How I Explained REST to My Wife
http://tomayko.com/writings/rest-to-my-wife
Looking at the documentation, the usage of the word "method" is probably a good indication whether that API is truly RESTful or not. There are a couple of resources that might actually qualify as such, like friends/<user-id> or favourites/<user-id>, but most of the resources are really just procedures, like account/update_profile_image for example.
The way I see it, in REST an URI should really just specifiy a thing, and not what you are going to do with it. If there is a verb in the URI (like update), you are most likely doing it wrong.
As the REST FAQ explains, the term "REST" is used to cover a wide array of things, including stateful applications that are structured in a RESTful style. Because the state is mostly being passed by the user in a cookie rather than stored on the server, it's considered RESTful. Roy Fielding (who invented REST) commented that as long as the entire state is being passed by the user, rather than a reference to state on the server, it's RESTful, since the same GET request will return the same result. Twitter's REST API is close to doing this, but not 100% there. It's not strictly the original meaning of "REST," but the interface and general philosophy are similar enough that it generally gets pulled under the same umbrella.
Technically, no, it's not RESTful. It's not stateless (a.k.a. idempotent as you mentioned) for one thing.
Reading the Twitter API i've come under the understanding that the RESTful API will be obsolete in a couple of weeks. Instead you should use the OAuth authentication method.