By RESTful best services there is the HATEOAS principle which told us that we should not allow the client to build resource URL-s. If we follow this principle, it will be pretty hard to share the current state of the client. For example if you have a REST service on the server, and you gets data via AJAX with a single page javascript client, then you will have 2 urls. One for the client state, and one for the result you got from the REST service. You can share only the client state with the use due to pushState... If somebody runs the client with a previously shared url, then her client won't know about the url of the REST service it should call, because the client cannot build URL-s, just receive from the REST service and utilize it.
For example:
I browse the http://my.client.com
the page gets the root resource from the http://my.api.com, and return a link
the link contains the http://my.api.com/users url, with rel user collection
after that the client displays a button with label: userlist
I click on that button, the client get the data from the api, and prints the user list
if I want to share the user list with my girlfriend, then I have to change the browser url from the client with pushState, for example from http://my.client.com to http://my.client.com/users
after that I send that url to my girlfriend
she copy-pastes that into her browsers address bar and presses enter. after that the client says a huge wtf, because - like John Snow - it knows nothing about what state that url means...
This problem can be solved, if we allow the client to build GET http://my.api.com/users from the url: http://my.client.com/users, but this won't be RESTful, because the client should not build api urls...
If I want to display a nested menu in the client, then that is another problem, because I don't want to send the whole menu tree in every answer. I could create a menu projection for every resource, or use the OPTIONS method, or a custom method to send that data, but that would be a pain in the back. This can be solved by following the rel=up links - got from the REST service - in series, but if I don't know from where should I follow, it will not work...
This problem occurs by google bots too...
How can I both solve this problem, and stay inside the boundaries of the HATEOAS principle?
Normally we don't want to share all of that information with anybody, so we cannot export all of that just the current page we are in.
There is nothing wrong with storing the whole resource on the client and then pushing it up to the server to change the state on the server. If you are worried your resources are getting too large though you could break the resources out a bit. So say you have an order resource and that needs to associate with an address. You don't need to put the address in the order resource, just a link to the address to use. The user can add or alter that address independently. So you might have something like
www.myapi.com/users/1234/shippingaddresses/default
And the client can PUT a new address to this resource. Then in the body of the order resource you can have a link to this resource
POST www.myapi.com/users/1234/orders
{
...order information...
"shipping_address": "www.myapi.com/users/1234/shippingaddresses/default"
}
To be RESTful the client should not build that URL, it should have been given it by the server at some point in the recent past, possibly when the users is selecting which address to use. For example, in the previous step the client could have requested all addresses
GET www.myapi.com/users/1234/shippingaddresses
And presented the list of addresses to the user in a drop down list.
Related
I use an authentication service Auth0 to allow users to log into my application. The application is a Q&A platform much like stackoverflow. I store a user profile on my server with information such as: 'about me', votes, preferences, etc.
When new user signs in i need to do 1 of 2 things:
For an existing user - retrieve the user profile from my api server
For a new user - create a new profile on the database
After the user signs in, Auth0(the authentication service) will send me some details(unique id, name and email) about the user but it does not indicate whether this is a new user(a sign up) or a existing user(a sign in).
This is not a complex problem but it would be good to understand best practice. I can think of 2 less than ideal ways to deal with this:
**Solution 1 - GET request **
Send a get request to api server passing the unique id
If a record is found return it
Else create new profile on db and return the new profile
This seems incorrect because the GET request should not be writing to the server.
**Solution 2 - One GET and a conditional POST request **
Send a get request to api server passing the unique id
The server checks the db and returns the profile or an error message
If the api server returns an error message send a post request to create a new profile
Else redirect to the home page
This seems inefficient because we need 2 requests to achieve a simple result.
Can anyone shed some light on what's best practice?
There's an extra option. You can use a rule in Auth0 to send a POST to the /users/create endpoint in your API server when it's the first time the user is logging in, assuming both the user database in Auth0 and in your app are up-to-date.
It would look something like this:
[...]
var loginCount = context.stats.loginsCount;
if (loginCount == 1) {
// send POST to your API and create the user
// most likely you'll want to await for response before moving on with the login flow
}
[...]
If, on the other hand, you're referring to proper API design and how to implement a find-or-create endpoint that's RESTful, maybe this answer is useful.
There seems to be a bit of disagreement on the best approach and some interesting subtleties as discussed in this post: REST Lazy Reference Create GET or POST?
Please read the entire post but I lean towards #Cormac Mulhall and #Blake Mitchell answers:
The client wants the current state of the resource from the server. It is not aware this might mean creating a resource and it does not care one jolt that this is the first time anyone has attempted to get this resource before, nor that the server has to create the resource on its end.
The following quote from The RESTful cookbook provided by #Blake Mitchell makes a subtle distinction which also supports Mulhall's view:
What are idempotent and/or safe methods?
Safe methods are HTTP methods that do not modify resources. For instance, using GET or HEAD on a resource URL, should NEVER change the resource. However, this is not completely true. It means: it won't change the resource representation. It is still possible, that safe methods do change things on a server or resource, but this should not reflect in a different representation.
Finally this key distinction is made in Section 9.1.1 of the HTTP specification:
Naturally, it is not possible to ensure that the server does not
generate side-effects as a result of performing a GET request; in
fact, some dynamic resources consider that a feature. The important
distinction here is that the user did not request the side-effects,
so therefore cannot be held accountable for them.
Going back to the initial question, the above seems to support Solution 1 which is to create the profile on the server if it does not already exist.
Background:
I have a single page application that pulls data from a REST API. The API is designed such that the only URL necessary is the API root, ie https://example.com/api which provides URLs for other resources so that the client doesn't need to have any knowledge of how they are constructed.
API Design
The API has three main classes of data:
Module: Top level container
Category: A sub-container in a specific module
Resource: An item in a category
SPA Design
The app consuming the API has views for listing modules, viewing a particular module's details, and viewing a particular resource. The way the app works is it keeps all loaded data in a store. This store is persistent until the page is closed/refreshed.
The Problem:
My question is, if the user has navigated to a resource's detail view (example.com/resources/1/) and then they refresh the page, how do I load that particular resource without knowing its URL for the API?
Potential Solutions:
Hardcode URLs
Hardcoding the URLs would be fairly straightforward since I control both the API and the client, but I would really prefer to stick to a self describing API where the client doesn't need to know about the URLs.
Recursive Fetch
I could fetch the data recursively. For example, if the user requests a Resource with a particular ID, I could perform the following steps.
Fetch all the modules.
For each module, fetch its categories
Find the category that contains the requested resource and fetch the requested resource's details.
My concern with this is that I would be making a lot of unnecessary requests. If we have 100 modules but the user is only ever going to view 1 of them, we still make 100 requests to get the categories in each module.
Descriptive URLs
If I nested URLs like example.com/modules/123/categories/456/resources/789/, then I could do 3 simple lookups since I could avoid searching through the received data. The issue with this approach is that the URLs quickly become unwieldy, especially if I also wanted to include a slug for each resource. However, since this approach allows me to avoid hardcoding URLs and avoid making unnecessary network requests, it is currently my preferred option.
Notes:
I control both the client application and the API, so I can make changes in either place.
I am open to redesigning the API if necessary
Any ideas for how to address this issue would by greatly appreciated.
Expanding on my comment in an answer.
I think this is a very common problem and one I've struggled with myself. I don't think Nicholas Shanks's answer truly solves this.
This section in particular I take some issues with:
The user reloading example.com/resources/1/ is simply re-affirming the current application state, and the client does not need to do any API traversal to get back here.
Your client application should know the current URL, but that URL is saved on the client machine (in RAM, or disk cache, or a history file, etc.)
The implication I take from this, is that urls on your application are only valid for the life-time of the history file or disk cache, and cannot be shared with other users.
If that is good enough for your use-case, then this is probably the simplest, but I feel that there's a lot of cases where this is not true. The most obvious one indeed being the ability to share urls from the frontend-application.
To solve this, I would sum the issue up as:
You need to be able to statelessly map a url from a frontend to an API
The simplest, but incorrect way might simply be to map a API url such as:
http://api.example.org/resources/1
Directly to url such as:
http://frontend.example.org/resources/1
The issue I have with this, is that there's an implication that /resource/1 is taken from the frontend url and just added on to the api url. This is not something we're supposed to do, because it means we can't really evolve this api. If the server decides to link to a different server for example, the urls break.
Another option is that you generate uris such as:
http://frontend.example.org/http://api.example.org/resources/1
http://frontend.example.org/?uri=http://api.example.org/resources/1
I personally don't think this is too crazy. It does mean that the frontend needs to be able to load that uri and figure out what 'view' to load for the backend uri.
A third possibility is that you add another api that can:
Generate short strings that the frontend can use as unique ids (http://frontend.example.org/[short-string])
This api would return some document to the frontend that informs what view to load and what the (last known) API uri was.
None of these ideas sound super great to me. I want a better solution to this problem, but these are things I came up with as I was contemplating this.
Super curious if there's better ideas out there!
The current URL that the user is viewing, and the steps it took to get to the current place, are both application state (in the HATEOAS sense).
The user reloading example.com/resources/1/ is simply re-affirming the current application state, and the client does not need to do any API traversal to get back here.
Your client application should know the current URL, but that URL is saved on the client machine (in RAM, or disk cache, or a history file, etc.)
The starting point of the API is (well, can be) compiled-in to your client. Commpiled-in URLs are what couple the client to the server, not URLs that the user has visited during use of the client, including the current URL.
Your question, "For example, if the user requests a Resource with a particular ID", indicates that you have not grasped the decoupling that HATEOAS provides.
The user NEVER asks for a resource with such-and-such an ID. The user can click a link to get a query form, and then the server provides a form that generates requests to /collection/{id}. (In HTML, this is only possible for query strings, not path components, but other hypermedia formats don't have this limitation).
When the user submits the form with the ID number in the field, the client can build the request URL from the data supplied by the server+user.
I'm working on a SPA which is a client to a RESTful web service. Both the client and server are part of the same project, i.e. I can modify the code for both sides freely. I've been reading up on RESTful API design to try and make sure I'm doing everything the "right" way. One of my takeaways from reading is that a RESTful service should publish hyperlinks so clients can access more information, and that clients should have no hardcoded information about service URLs other than an entry point. Using hyperlinks allows the client to be more flexible in the event that the server makes URL changes.
However I can't figure out how this architecture is supposed to work when users are allowed to link to a specific client state. For example:
One of the views is a list of books available for purchase. The client sets the browser's location to /books/ to identify this page, and the backend data comes from an endpoint /api/books/, retrieved from an API entry point that publishes that URL. The service URL responds with a JSON document like this:
[
{"title": "The Great Gatsby",
"id": 24,
"url": "http://localhost/api/books/24/"},
< and so on >
]
The client uses this to generate readable links that, when clicked, go to a detailed view of a single book. The browser's location is updated to /books/the-great-gatsby/24/ so users can bookmark this view and link to it.
How does the client handle when users click this link directly?? How would it know where to get the information for this book without having a hardcoded URL?
The best I could come up with is the following sequence of requests:
GET /api/ - view which services are available (to find there are books at all)
OPTIONS /api/books/ - view a description of what operations are available on books (so e.g. it can make sure it can find books by ID)
GET /api/books/?id=24 - See if it can find a book with an ID that matches the ID in the browser's location.
GET /api/books/24/ - Actually retrieve the data
Anything shorter would imply that the client has hardcoded knowledge of the API's URLs. However, from a web app point of view, this seems grossly inefficient.
Is there some trick I'm missing? Is there a way for the client to "know" how to get more detail about book ID 24 without somehow having the /api/books/24/ endpoint hardcoded?
if you request this resource /books/the-great-gatsby/24/ from the server, the server should respond with something specific to that URL. Currently, you are probably analyzing window.location which is a bit of a hack.
If /books/the-great-gatsby/24/ is static content, then you have very little choice: You store the client's current state explicitly somewhere (i.e. /books?data=api/books/24 or implicitly /books/the-great-gatsby/24/ which then leads to the client having to know how to translate that to an API resource.
The RESTful way is to use hypertext to indicate where any related resources (i.e. your data to render is) are which makes a tag an appropriate choice.
i.e. ditch the static content, and render /books/the-great-gatsby/24/ with a <head><link href="api/books/24" ....></link></head>
However, if you always retain control of your client side and don't plan to publish the API to third parties, you might be more productive ditching RESTful and just go RESTish.
The Resource URL Locator pattern
In this answer: user is (the human interacting with) the internet browser, client is the Single Page Application (SPA) and server is the REST API.
Deep linking is a convenience of the client to the user; the client itself may still not have knowledge of the server's URLs, so the client must start at the root URL of the server. The client uses content negotiation to indicate which media type it needs. The first request of the client to the server when bootstrapping itself could be as follows:
GET /?id=24 HTTP/1.1
Accept: application/vnd.company.book+json
Optionally, the client uses the id querystring parameter as a hint to the server to select the specific resource it is looking for.
When the server has determined which resource the client is looking for it can respond with a redirect to the canonical URL of the resource:
HTTP/1.1 303 See Other
Location: https://example.com/api/books/24
The client can now follow the redirect and get the resource it needs to bootstrap the application.
#Evert's comment got me thinking. Isn't a deep link or a bookmark just a continuation of application state from a previous point in time? It doesn't really matter how much time has passed after the previous application state transition.
You could say that the 'current' application state in HATEOAS is the last followed link. The current state must be stored somewhere and it might as well be stored in the application URL.
Starting the application at a deep link indicates to the application that it should rebuild the application state by requesting the resource indicated by the application URL. If the resource is no longer available or has moved, the server should respond with a 404 Not Found or 301 Moved Permanently respectively.
With this approach the server is still in control of the URLs. The application follows the hypermedia links in the server's responses and doesn't generate URLs itself.
I know that to make a stateless application, we need to transfer the user state back and forth instead of server holds the user state.
However, there must be some states stored in the server, I read this article that the state stored in server is called resource state.So if I am right, client state which we often call should be the same as application state.
So, how do I distinguish these two, since it will determine that whether they should stored in server or transferred.
Take a shopping cart as an example.
If there is 5 steps before a user to complete his purchase, the user's phase where he is(#3,#4) in seems to be an application state, but does this mean if they close the browser and click on pay again, he will have to start from the step1?
What about the items in his chart? If we treat it as application state, we need to put all of the items in the request. But if we do this, when user close the browser and login again, he will not able to find his items again, since the browser can not remember all the items. So it seems we should treat it as a resource state. But if so, when a user click on pay , they will have a different page: go to pay or say "your cart is empty" based on whether his shopping cart is empty or not. So , the same requests with exactly the same param input, comes out the different result, can we still say it is stateless?
Maybe I understand something wrong, can any body please answer how to distinguish different kinds of state and how to treat them differently?
Resource state is a state that needs to be persistent and survivable even after client disconnect/restart/session end/whatever.
Application state should live on the client and should be supplied with each client request(if we are talking about REST architecture and planning to scale our application well).
How to distinguish application state and resource state?
It depends on the task your are working on. E.g. if you are trying to figure out where to save index of the picture that is currently viewed in your gallery, probably, you could do it in your Application state, because you, likely, don't need this state to survive for the next session of this client. Of course, you can save it in your Resource state(database), but it would be overhead(a lot of effort for a very small gain).
But if your are working on multistep purchasing process, probably, it's better to save state of this process in your Resource state(database), because you want this state to be saved permanently. Otherwise, your clients need to refill a lot of information after disconnect/restart/whatever.
Of course you could do it in cookies for example(and it would be Application state), and this state can live after browser restart. But it has the two downsides: 1)This state unavailable on other user's devices, 2)If you are creating genuine REST service, cookies would complicate client's life, because not all clients operate cookies well(except browsers).
Let me just quote one paragraph of the book RESTful Web Services :
The Flickr
web service lets you upload pictures to your account, and those pictures are stored on
the server. It would be crazy to make the client send every one of its pictures along with
every request to flickr.com, just to keep the server from having to store any state
The application state is related to the path that the client can follow to make some actions.
For example, when consulting an article, a link "add to cart" appears. When consulting his cart, a link "pay your order" is provided if you have one article in your cart otherwise this link does not appears. Feel free to the user to make its own application state based on the link that he follows. Basically, application state is a matter of context.
One other quote from the same book mentionned earlier before I go back to you example:
Resource state stays on the server and is
only sent to the client in the form of representations. Application state stays on the
client until it can be used to create, modify, or delete a resource. Then it’s sent to the
server as part of a POST, PUT, or DELETE request, and becomes resource state.
So let's say that you have some authentification mechanism (based on token). And to one user account is associated one cart.
When you are adding items in your cart, you are modifying your cart resource. As resource state are server-side, it's on server.
Suppose that you disconnect, and reconnect like described in your first point. The cart is still here.
As long as the client send the different authentification credential at each request, your application remains stateless.
A good discussion on SO about how to manage it: Do sessions really violate RESTfulness?
Now, what about the fact that: consulting your cart can leads you to 2 different action depending on whether it has items or not.
Pretty simple. What is served by the server to the client depends on the resource state maintains by the server.
A very simple example on this good website. You can see that depending on the amount of money on the account, the server provides a link to the client to make a withdraw or not.
Feel free to the client to make its own application (again) and to follow the link or not.
I recommand you to take a look at HATEOAS and the Richardson Maturity Model that explains it.
By the way, the quotes from the 2 paragraphs are from the same author that this model.
Is it appropriate to perform actions with REST, other than simple create (POST), read (GET), update (PUT), and delete (DELETE)? I'm kind of new to the whole RESTful theology, so bear with me, but how should I accomplish the following:
I have a web service that needs to talk to another web service. Web service A needs to "reserve" an object on Web service B. This object has a timeout of validity, but can be deleted immediately if need be. It's essentially a glorified permissions system which requires web services to reserve a space on web service B before taking any actions.
My initial thought was to 1. enable authentication of some sort, 2. in the serverside response to a GET call, reserve the space and return the result, and 3. provide immediate "unreservation" of the object via a DELETE call. Is this still being RESTful?
Yes, it's OK to perform actions with rest. What matters is that these actions should be guided by the representations you exchange.
If you think about the way the web works (via a browser), you do this all the time: you get an HTML form that lets you choose a number of actions you can perform. Then, you submit the form (typically via POST) and the action is performed.
It's good to be able to use DELETE via a programmatic client (which is something that non-AJAX requests in browsers wouldn't support), but the overall approach of a RESTful system should be very similar to what you find for websites (i.e. the focus should be on the representations: the equivalent of web pages in your system).
GET shouldn't have side effects, so don't use GET to make the reservation itself, use something like POST instead.
No - unlikely to be restful
From your description ...
2. in the serverside response to a GET call, reserve the space and return the result
GETs should be idempotent. For this reason alone, your service is unlikely to be restful because the state of the system after the first GET is different.
You really need to consider that a Reservation is a resource and should be created with a POST to a reservations container which will return the URI of the new resource in the Location header of the HTTP response. This UrI can be used by Get to return the resource and updated with a PUT
Post should be used to extend an existing resource and Put for replacing the state of a resource. In your case, consider the Post to be updating a list of Reservations and returning the URI of the new resource (not just the I'd). Put can be used for changing the state associated with the resource identified by the UR
You're on the right track, but your reservation of the object should be with a PUT; you're PUTting a reservation on the object, i.e. changing the underlying object.
PUT is the right verb here, since you know what resource you're modifying, and it should be idempotent for multiple requests.