I want to add, or replace a coupon to an order via api. I thought in this two possibilities
PATCH /api/orders/{id}
{ "couponCode": "test"}
PATCH /api/orders/{id}/coupon/{couponCode}
I like the second because it's important in the application to apply a coupon code, and this url specifies it very well.
Are first and second valid possibilities following REST? The second option is valid with PUT and PATCH HTTP Methods?
Which do you think is better?
Thanks
The PATCH method is not particularly RESTful on its own. REST is about transferring state, and PATCH doesn't really do that, instead it sends an instruction for an update.
So to make things RESTful what you will want to do is a PUT request to create and replace the state of a coupon in full.
With that being out of the way, this is not an endorsement against using PATCH, but my idea about this is that it's a good idea to:
Provide a proper PUT request to fully replace existing state.
With that in place add support for PATCH to optimize things that might be slow or clumsy.
So if you want to use PATCH on /api/orders/{id}, I would first wonder: how does the PUT version look like?
I don't fully understand what a PATCH on /api/orders/{id}/coupon/{couponCode} would mean. Are you updating the coupon code? It's odd because the code exists in the uri. A DELETE + a PUT makes more sense to me. Or maybe the HTTP MOVE method might even help? (MOVE also falls in the 'not RESTful camp but it's a nice optimization for GET + DELETE + `PUT).
If an order only ever has 1 coupon, I would prefer a uri structure like /api/orders/{id}/coupon because it's a nice singular resource and it makes total sense to replace it with PUT (or PATCH it).
Related
Is it possible to make the same field compulsory for POST and optional for PUT requests for REST API? Or it depends on teqnology used to implement this request?
For example, there is a POST request to create Car objects and this object has a field model_id which is actually chosen from a dictionary of models. And the POST request requires model_id because the car must have model_id defined.
And I want to have a PUT method which changes some field e.g. serial_num, manufacture_date, color etc. even model_id. But I want this PUT method to change model_id as optional parameter, e.g. I just want to change color and it is Ok.
So is this possible in REST? Does some technologies that implement these request could not allow me to make different set of optional/compulsory params for POST ant PUT?
Well, you can do whatever you want here. Nobody will kill you if you check fields in the request body and return an error if model_id is specified (or not).
Some guys use POST method to update entities in API.
If you want to be closer to standards better use PATCH for partial updates.
You can find a lot of interesting info here:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
Use of PUT vs PATCH methods in REST API real life scenarios
https://www.rfc-editor.org/rfc/rfc7231#section-4.3.4
https://www.rfc-editor.org/rfc/rfc5789
One important thing from 4. source:
The PUT method is already defined to overwrite a resource with a
complete new body, and cannot be reused to do partial changes.
And another one sentence from 3. source:
Generally speaking, all implementation details behind the resource interface are intentionally hidden by the server.
Assume you have a REST service that already gets users by id, so the url looks something like
GET /users/{userId}
But you want to create a duplicate web service that gets users by email, so:
GET /users/{email}
Which is better?
Method 1:
Same method:
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Method 2:
Different Method:
GET /users/{userId}
GET /usersByEmail/{email}
Since there is no actual overlap between email addresses and IDs. I would just use same endpoint for both. Especially if GET /users/{id} is already a published interface.
So, I would go with 1st method.
GET /users/{identifier}
Then on the API server you have to add a small check, whether {identifier} is a number or not.
I would also like to note, that "pretty URLs" do not make it REST :) You probably will want to watch this lecture: https://www.youtube.com/watch?v=pspy1H6A3FM
My personal preference would be,
GET /users/id/{id}
GET /users/email/{email}
But it all depends on what you the rest endpoints to look like.
Which is better?
REST doesn't care; from the perspective of the client, the URI is opaque. The clients concerns are following links/submitting forms/completing templates.
Information encoded into the URI is done at the server's discretion and for its own exclusive use.
So you can use any spelling you like. As a rule, it's a good idea to conform to local spelling conventions (in much the same way that your variable names in code should conform to your coding conventions). But your clients shouldn't need to know the details of those conventions.
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Note that you aren't necessarily deeply committed to one approach; that's part of the point of decoupling the identifiers from the representations. For instance, your implementation could just as easily look like
/users/{input}
...
if(isEmail(input)) redirectTo(/users/email/{input});
else redirectTo(/users/id/{input});
which allows clients that have bookmarked the original URI to arrive at the correct resource.
I have a REST service.
And now I need to have functionality to move some child resources from one parent to another, for example move a book from one author to another.
My variant is:
POST /api/books/x/moveto/y
But how to create such architect the RESTful way?
From a REST point of view, URLs should be used to locate the resources rather than expressing operations. To express operations, the existing HTTP verbs should be used.
Looks like your "move" operation is all about replacing the author of the book.
And the PUT method seems to be the way to go:
4.3.4. PUT
The PUT method requests that the state of the target resource be
created or replaced with the state defined by the representation
enclosed in the request message payload. [...]
So, you can have an endpoint like the following:
PUT /api/books/{bookId}/author
And the request payload will contain a representation of the new author.
I think in this case updating the author as suggested in Cassio's answer is a good solution. For less obvious "actions" I use PATCH endpoints. Consider archiving a book:
PATCH /api/books/{bookId}/archive
The intent is obvious -- archive the book with this identifier. For more complex actions, include a body or use a query string parameter. For instance, moving a book out of one category and into another (assume a book can have 0-many categories):
PATCH /api/books/{bookId}/move
{
fromCategoryId: 100,
toCategoryId: 200
}
Or:
PATCH /api/books/{bookId}/move?fromCategoryId=100&toCategoryId=200
In the end, IMO, what matters most is readability and consistency. There is not necessarily a "right" way to do this sort of thing.
What's the correct "RESTful" URL for an action that adds a child record to a parent record?
For example, if I wanted to provide a URL for adding a "comment" record to an "order" record, how should I format it?
My first thought was something like:
PUT http://example.com/order/12345/comment/add
I work in Django, which uses a similar pattern, so this seemed most intuitive. However, reading over some RESTful design guides like this one suggests that this might be bad practice, as they argue the "PUT" and "add" are redundant and therefore might create confusion.
I would do the following:
POST http://example.com/order/12345/comment
The put action and the add part of the url are redundant. But there is no hard rule on any of this. I see apis having that form, even from major vendors, and sometimes simply remark "The put action and the uri segment are redundant" Sometimes I say nothing at all and just call the endpoint. If I were writing an api, I would probably leave off the add part.
there are few points to make your request RESTful:
1) Use resources names in the URL in plural and not in a singular form (orders instead of order)
2) never use ACTION names in your URL such as (ADD) in "comment/add"
3) since you are adding a "NEW" comment without knowing any IDs of hands you should use POST request.
Finally, the URL I would recommend is:
HttpVerbs = POST
http://api.example.com/orders/12345/comments
That should add a new comment to your order#12345
There is no one-size-fits-all answer to your question. Rest URLs can be whatever you want them to be. At the end of the day, they are routes that get mapped to a method. I wouldn't worry too much about the "best" URL. I prefer to find a standard that works for me and then move on to bigger, more important things. As long as clients know what the URL is, they will be fine.
In my app there is a button which (when clicked) should apply some mutation to all entities (of a certain type). Assuming my entities are "purchases" clicking on the "confirm all" button should result in the server/db setting the "confirmed" field of all "purchases" to "true".
I have the code that does this on the server side. My question is this: what is the URI that I should use for this action?
POST seems like a wrong choice as this action is idempotent. Thus, I am left with PUT. two ideas come to mind:
PUT /purchases?confirmed=true
PUT /purchaes/__all__?confirmed=true
Is there any well established convention?
EDIT
There is a third option (suggested by Markus):
PUT /confirmations/?confirmed=true
Of course, this can work and clearly has its merits. The (only) problem that I find with it is the confirmations is not an en entity in my system. In particular there is no GET /confirmations/some_id URI which may be confusing.
Firs of all, the URI you should use for this operation is whatever URI the collection of purchases returned for that action. The URI semantics shouldn't matter.
Second, when we say POST isn't idempotent, what we are saying is that the client can't assume by default that the operation is idempotent. The semantics of the POST method are entirely within your control, and that's why they must be documented and you can't rely on the client knowing beforehand what it does, as is the case with GET, PUT and DELETE.
In simple terms, having a PUT operation that isn't idempotent is a violation of the HTTP method semantics, but having a POST that is idempotent is fine.
Third, what you're doing is RPC, not REST. For instance:
PUT /purchases?confirmed=true
You're simply calling a method by passing parameters. The only way this could make sense in REST would be if you were creating or replacing a set of purchases to replace the subset where confirmed=true, which would be the exact opposite of what you want. If you want to do something like that, you should use POST, not PUT.
It's clear that your confirmation is a partial update, so you shouldn't be using PUT at all. As a general rule, if you're trying to define a separate semantics coupled to a particular resource for GET, PUT, PATCH and DELETE, you're doing wrong. Those methods should be generic and work in the exact same way for everything. If you need to couple some URI and method to a particular resource state transition, do it with POST.
I don't know the details of the API, but it looks like you're using query string parameters as payload parameters interchangeably. That's not a good idea either, since you can't treat URIs as atomic identifiers.
If your URIs were atomic, you could say this returns all unconfirmed purchases:
GET /purchases?confirmed=false
And you could document POST as the method to perform partial updates in bulk, changing the filtered subset:
POST /purchases?confirmed=false
{ "confirmed": true }
If you insist on using PUT, you should do something like this. If you have the URI below which returns a global confirmed status by reducing all purchases with AND:
GET /purchases/confirmation
{ "confirmed": False }
Then you could make something like:
PUT /purchases/confirmation
{ "confirmed": true }