How many sub-collections can have a resource?
Just imagine that we have this model:
accounts -> posts -> comments
Everything is clear for accounts-posts pair.
/accounts/{account_id}/posts/{post_id}
But what about comments? What is a proper way to point to a single comment?
/posts/{post_id}/comments/{comment_id}
or
/accounts/{account_id}/posts/{post_id}/comments/{comment_id}
or (direct pointing)
comments/{comment_id}
The general rule of thumb is to only go one layer of subresources deep. An account may have many posts like you show, and a post may have many comments, but since the post id is unique, including the account id is a bit redundant when trying to get the comments for a post.
/accounts/:account_id/posts
/posts/:post_id/comments
Ruby On Rails also lists this in their docs (just for a bit of a citation). https://guides.rubyonrails.org/routing.html#limits-to-nesting
Additionally, if you already have the id of a resource you don’t need to nest it. As short of a route that gets the job done is preferred.
/comments/:id
Related
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 :)
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.
I have some questions about Rest API and relationships.
I know the questions of relationship is always tricky with Rest.
I have some users, posts (created by user), relationships between users (imported from fb), interactions on posts (created by user) and users can like a post.
User can create a posts which will be seen only by others users who have a relationship (up to 2 jump, like friends of friends) with the poster and then can create interactions on the post.
We do a filtering on the backend based on your authentification and just do the magic on /posts which will return you the list of post that you can see.
It feel a bit funky to me because it make the same endpoint (/posts) will return different set of data based on the current user. We could of course pass a parameters (?viewable_by_user_id=:id) to reflect it a bit more, but I wonder if I can do anything to improving caching.
I'm thinking of improving our API to a v2 with this endpoints:
GET/PATCH/DELETE /users/:id
POST [post] /posts: create a post (using current auth user as the owner of the post)
or
POST [post] /users/:id/posts: create a post for this user
GET /users/:id/posts : get posts created by the user
GET /users/:id/stream : get posts "viewable" by the user (this is the one I'm strugeling with)
or
GET /posts?viewable_by_user=:id
GET /users/:id/like : get posts liked by the user
POST [post_id] /users/:id/like : like a post
POST [interaction] /posts/:id/interactions : create an interaction on the post for the current user
GET /posts/:id/interactions : get post's interactions
GET/PATCH/DELETE /interactions/:id
Any thoughts on how I could make the path reflect a bit more the relationship?
I've thinking on creating an endpoint for relationships but seem a bit to complex to maintain (users don't create relationship manually, we pull them from fb)
Thank you for any feedback, and let me know if my question is too ambiguous or irrelevant.
What if you think of it as this: (Note that I just like putting "posts" first since it tells what and then the restrictions go to the right of that. You may like the other order.)
GET /users/posts/<viewer>/<creator>
This gives some degenerate cases:
GET /users/posts/<me>/<me>
to get all the posts I have created
GET /users/posts/<me>
to get all the post from all other users
GET /users/posts/<me>/<stranger>
would return nothing because I am not allowed to see the stranger's posts
GET /users/posts/<me>/<friend>
would return the posts from my friend.
NOTE: In all cases, all posts returned are those allowed to be seen
Numerical IDs vs names
As an example, which of these would you choose for identifying a single transaction, from a single bank account, for a single company:
/companies/freds-painting-ltd/accounts/savings/transactions/4831
/companies/freds-painting-ltd/accounts/1/transactions/4831
/companies/62362/accounts/1/transactions/4831
You idiot, something totally different! Crikey, did you even READ Fielding's dissertation?
Now, I think the 1st one is the most readable. If I have more than one company, or if I'm someone like an accountant managing multiple companies, it's immediately clear which company, and which account, I'm looking at. It's also more bookmarkable/emailable and would prevent 'fishing' for other companies by changing the company ID. I would want transaction IDs to be unique to an account (I.e. Both 'savings' and 'current' accounts could have transaction '1'
A 'company' will be my 'top-level', or 'first class' resource. Nothing at all would ever be shared between companies. As such, it would be the ideal candidate for a shard (or 'ancestor'/'namespace' in Google App Engine parlance). So I'd only have to worry about the account names being unique within one company. Every company could have an account called 'savings'.
Not sure what the situation in the rest of the world is, though LTDs or PLCs in UK would have a unique name, there could be many 'Dave's Window Cleaning' businesses (what's know as a trading name).
The business owner(s) could potentially opt for the top level /company/company-name URI to be public, and contain some basic details like their website, contact details etc, but everything below that would NEVER be accessible by search engines.
So my thoughts/concerns are:
1) Is it reasonable, when someone signs in to add their business, to say "Sorry, 'Dave's Window Cleaning' business is taken. How about 'Dave's Window Cleaning Portsmouth' (Having taken their location in another field)? My worry with this is that, for a more well known company, you're giving away the fact that they have an account with you. Or that someone could use that form to search for names. Perhaps not a biggie.
2) The size of the company name. Would it be reasonable for a name like 'Dave's Window cleaning, gardening, and loads of other stuff'? Thus creating a URL like 'daves-window-cleaning-gardening-and-loads-of-other-stuff/'
3) How to deal with someone changing their business name - I would approach it by creating a new company with that string ID, copying over everything, then deleting the old resource. The original URI would return 404 rather than redirecting - as you can't guarantee someone else won't want to take the now unused name, or even if more than one person has used the same name in the past.
4) Should the 'real' unique ID be an number in the back end, and for every request to be handled by first doing a query for what company ID this name actually related to.
5) The impact of searching for a transaction in the persistence layer.
6) The possibility of URL rewriting, but then that wouldn't work cleanly in GAE, nor would it solve the issue of ensuring company names are unique.
RESTful webservice vs RESTful website
So, we potentially have this lovely RESTful webservice that the latest snazzy iphone/android app can use (delusions of grandeur). But what about the main website itself? I note, right now, that the URL I see at the top of my page is not 'RESTful': /questions/ask is an action. There is no 'ask' resource on the server. It's more the state of the page, the preparation for POSTing to /questions/ - or if I'm editing, PUTing to /questions/{id}
I also note that Stackoverflow has URIs like /questions/362352/name-of-the-question, and that the latter part can be omitted, and one will be redirected to it.
Should I host a completely separate webapp that consumes my lovely webservice (from the same domain)? Do I even need a separate REST server, or can I rely on content negotiation (JSON/XML) and HTTP verb to select the right method (I'm using Jersey), and return the right representation?
So I could have /companies/aboxo/ return the whole HTML page (using stringtemplate.org) if it's a GET /,text/plain or test/html, and JSON/XML for others?
But what happens for 'add/edit/delete' transaction? Would GET / /companies/freds-painting-ltd/savings/transactions/?template=add be ok (or GET ../transactions/352?template=edit), and that would return the right HTML?
Thinking about this last detail is driving me mad for some reason.
Comments, suggestions, outright ridicule - all welcome!
Marcos
Rails solves the "id vs name" problem by displaying both in the URL but using only the id to actually identify eg:
/companies/62362-freds-painting-ltd/accounts/1-savings/transactions/4831
ie - for the ones that have a "pretty url" the function that generates your path write both the id and the name... but for your router, where relevant: you strip off everything thats not the id.
incidentally, it means your customer could actually write whatever they like into the URL and it'd make no difference:
/companies/62362-i_luv_blue_turtles/accounts/1-your_mum/transactions/4831
and your router still just sees:
/companies/62362/accounts/1/transactions/4831
:)
For a cannonical URI I suggest just /transactions/{id} as I presume the transaction knows what the company and account is. Therefore, #4 :-)
Is SEO a concern? I presume you don't want random folks off the internet googling for X company's transactions?! Therefore, I would just keep names (which may change) out of the URI.