I need to design an operation “duplicate” for "articles".
My thought was: a POST on apibaseurl/articles/{id}/duplicates and returning a 200 OK with the URI of the created duplicate, which's URI however will conform to the template apibaseurl/articles/{id}.
When issuing a GET to apibaseurl/articles/{id}/duplicates however, there will not necessarily be a list of duplicates (meaning: the server will not keep track of all duplicates created for an article - the "duplicate" relationship is ignored by the server outside the scope of the request)
Questions:
is my suggested solution OK?
does it not violate any RESTful principle by having the URI of the created object point to a location not under the resource under which it was posted?
would I have to provide a client with the possibility to list all duplicates for an article?
is my suggested solution OK?
It looks fine to me.
does it not violate any RESTful principle by having the URI of the created object point to a location not under the resource under which it was posted?
No, that is not necessary. You POST to a collection resource but this does not force you to return a Location header pointing inside this collection.
would I have to provide a client with the possibility to list all duplicates for an article?
If you have a use case for this, you could provide it. But if there is no business interest in listing the articles created as duplicates of an existing article, you don't have to.
Go ahead :)
Related
I am looking for a good URL, following REST principes, to "Move the competitor from team1 to to team2
My first guess is :
/teams/{oldTeamId}/{newTeamId}/competitors/{competitorId}/move
But it doesn't look much like REST.
Should I break it into 2 basics calls ?
Remove competitor from team1,
Add competitor to team2,
Should I remove some data from URL and pass it into the body ?
I don't really know what to do for this one.
Think about how you would implement this API as a web site.
You would probably have a link to a form -- it might be a form where the competitor, old team, and new team are all blank, or it might be a form where the competitor and old team are pre-populated. Your consumer updates the default information in the form as required, and submits it.
Notice the first point (raised by Roman Vottner as well) -- your consumer doesn't need to look at the URL at all. The client knows the HTML form processing rules, so it can create the correct HTTP request without knowing anything about the domain.
The second point is that, since the client is just submitting the form to wherever the HTML tells it to, you can make that anything you want.
One of the interesting properties of HTTP is cache invalidation. See RFC 7234, any non error response to an unsafe request will invalidate all cached representations of one resource.
So you can choose which resource gets invalidated by specifying its URI as the target of the form. In effect, it gives you a mechanism for ensuring that a consumer can read its own writes.
So some reasonable choices for the target might be
/teams/{oldTeamId}
if the team roster is the most important thing. Or
/competitors/{competitorId}
if the resource that describes the player is what is most important.
I don't really know what to do for this one.
Concentrate on make it easy to use. Your resource model is not your domain model is not your data model.
It will likely be useful to watch Jim Webber's talk REST: DDD In the Large to get clearer insights into what your "REST" API should really look like.
To answer your questions, I would not break it into two calls, I would however take some data from that (GET) url and put it in the body of your request. The request would probably be a POST or PUT (or maybe even patch), but definitely not a GET since something is actually changing.
As for a solution, how about a POST request to a /transfer. After all you are (could be) creating a new transfer which takes for example the player, their new team and maybe their old team.
I would use URL to identify the resource which in this case seems to be a competitor's team.
So would
Make the url as /competitors/{competitorId}/teams
Make the call PUT
Have a body with newTeamId and if required the oldTeamId.
I'm implementing a new REST API. In this API I typically POST to collections to create resources. For one of my resources, the ID is known before it is created. Does it make more sense to post to the collection with the ID in the body or to post to the instance (as yet non-existent) with the ID in the URL?
I'd say keep the existing endpoint and just add the ID in the body when POSTing to that collection, there's no point in adding a new separate route for what's basically the same thing.
From another thread: https://stackoverflow.com/a/18474955/1851581
You can also use PUT with the ID in the URL, instead of POST.
PUT is used for upserting, covering mainly updates but also the creation of the resource if it doesn't exist.
I ended up posting to the collection with the ID in the body. That keeps with the pattern elsewhere in my API. The only difference here is that the ID is supplied in the body.
TL;DR How to mix REST requests with some non-REST requests in SPA(frontend/backend)? Or might be I just get REST wrong?
We are planning new API for SPA and mobiles(plus probably some 3rd parties). There will be some requests which, I suppose, can't be covered by REST.
I am speaking mostly about requests which would make backend do something, which would modify state of document or give some additional info, based on document, but request itself is rather simplistic.
Here is really easy example. I want to add a comment to blog post. For example I might do it like this:
Create comment. POST /comment
Create connection between author and comment. POST /comment_author or PUT /comment with author_id.
Create connection between comment and post. POST /comment_post or PUT /comment with post_id.
I also could do something like POST /comment with {author_id, post_id} which actually seems most logical here.
Everything did work, comment added to blogpost and associated with author.
Now customer wants to get statistics for his comment, like words stats and letters stats. As a part of request I pass comment_id. Backend might update comment with stats data, it might create separate entity and link it with comment or it might just send me those stats for this comment without saving.
So what would be the choices?
I can do something like:
GET/PUT /comment/:id/stats. For me it seems already hack, because as a result I don't want a document of type comment, but document of different type. As well as I don't send stats with request, I calculate them on backend so using PUT seems wrong.
POST/GET /comment_stats/:comment_id. Seems legit, but if I don't have a document/entity of type comment_stats, that would mean that I actually ask backend to create something, backend would reply me OK/Created, but actually I don't have this document somewhere saved.
So, while I understand REST != CRUD, I thought to use REST for simple CRUD and, for cases like that, to use RPC. So in RPC scenario I would just call POST comment.stats(comment_id)
My questions are what would be better choice in this situation, as well as are my thoughts about rest/rpc right?
I would go with GET /comment_stats/:comment_id for proper separation of concerns, so that report code doesn't clutter the comment resource.
It doesn't matter if you don't actually have a comment_stats document, or how the data is represented on your backend. The REST API is just an abstraction over your backend.
In general, for any non-CRUD action like this, it's better anyway to create a new resource and deal with it as if it was a "machine": you send some instructions to the machine (via a GET or POST call). The machine executes it and then returns the result. A simple example would be an endpoint to convert images: you create an /image_converter end point (the machine), you POST an image to it, it converts it, and sends back the image. /image_converter would have no associated entity/document in the database but for the end user it's still a resource with a logical behavior.
I am trying to build a little web application with the MEAN stack (MongoDB, ExpressJS, AngularJS and NodeJS).
My question is very simple. If you take the example of a blog, it will contains blog posts, that you could list at this url:
GET /api/posts
You could also get the comments for that posts:
GET /api/posts/:postId/comments
and get a single comment:
GET /api/posts/:postId/comments/:commentId
The relation between post and comment is really obvious here, but does it still makes it mandatory to have it this way? or could I just perform my CRUD operations through /api/comments? In the end, a comment object in mongodb will always have a postId attribute anyway which will reference the post that it is related to... Moreover, the API will not be exposed and is strictly meant to be used by the application.
does it still makes it mandatory to have it this way?
No. This is not mandatory at all.
or could I just perform my CRUD operations through /api/comments?
Yes. This will result in cleaner resources URIs (endpoints).
You can also get post-specific comments with:
GET /api/comments?postId={postId}
Further, you could also drop the /api prefix if you are serving only an API at the given host.
Lets say I have resource representing images
PUT /images/[id] with path -> going to create me a new image resource if already present updates my resource
POST /images/[id] -> to change or update a resource Ex., image name
DELETE /images/[id] -> this will delete my resource
GET /images/[id] -> gets me the image details
Now the actual question. what if I need to add additional actions to the images ?. Lets say the image resource will respond to a red eye reduction action or any other like crop, resize
So how these action are considered and how this should be called in restful interface ?
/images/[id]/remove_redeye
/images/[id]/crop
/images/[id]/resize
Is the above calls valid in restful interface ? I am confused about what should these action should be considered(PUT POST)?
"Remove redeye", "crop", and "resize" all sound like actions which "change or update a resource." They would belong in a PUT action. (I think you mixed up PUT and POST in your question, refer to the verbs listed at w3c.)
How you convey the nature of the action depends on what's being POSTed. For example, if we were talking about a form sitting on top of a database record, the POST would simply be the data for that record. It wouldn't be necessary to specify which fields are being changed because the whole object is being POSTed in its new state.
Is the whole object being POSTed in its new state in this case? Or does the object live only server-side and the interface is just sending a request for some kind of action? It sounds like the latter to me, based on the information provided.
In that case you can include in the POST some more information about the action. Keep in mind that a POST can contain key/value pairs in its data and/or a larger and more complex POST body. This body can contain XML, for example, specifying a lot more information for the server to use in processing the request. Maybe something like this:
<image id="123">
<resize>
<width>200</width>
<height>200</height>
</resize>
</image>
This could even allow multiple actions within the same request, allowing the user to try various things client-side before committing them all in a single unit of work server-side. How you'd process that or if it's even applicable in this case is up to you, of course.
PUT /images/[id] means to add a new resource or to fully replace an existing one.
POST means to create (/images) or to modify a resource (/images/[id]). If you create a resource, the server may return that resource for you.
For several modifying actions on the same resource (POST), I tend to use a custom header to define the kind of modification. In this case your resources
/images/[id]/remove_redeye
/images/[id]/crop
/images/[id]/resize
would translate to:
POST /images/[id] HTTP/1.1
X-RESTAction [remove_redeye|crop|resize]