When building a RESTful API over HTTP, what is considered to be correct when wanting to add resources to a nested relationship (e.g. a user with posts)?
Post the new resource to:
/users/$user_id/posts/
Or post the new resource to:
/posts/
And setting the user ID in the POST data?
Sorry, but there's so much FUD about REST APIs, I'm still trying to figure a lot of things out.
Thanks in advance!
K.
I would put it in the
/users/$user_id/posts/
seems more correct,but if the userid data is sensitive i would use
/user/posts
and pass the $user_id in the body
Related
I have tried out the RESTful API concept and found out that its a great mindset for building resources APIs. For example, adding comment to post would be
POST /posts/{id}/comments
However, there are some cases, correct me if I am wrong, that the expected APIs can not really be model as a simple CRUD
For example, adding product to the system requires adding picture, adding multiple tags specify its category?
How do I do this the restful way?
1.) Do I force the API user to follow after multiple API calls?
POST /pictures -- add picture
GET /categories -- get selected category
POST /tags -- add tags
POST /products -- input picture, category, tags ids as JSON fields
2.) Do I use nested object which automatically do find all subresources?
POST /products -- input nested JSON array with picture/category/tags object field
In this case, all subresources will be existing resources instead of some (picture, tags) that should be posted.
Also, what would happen if adding picture succeed internally but adding tags failed?
3.) Do I just do a casual API? How does this fit with REST? Doesn't this break the RESTful idea?
POST /add_products
Is there any guide to deal with complex API for RESTful APIs?
Thank you.
In my opinion, one of the biggest misconception people have about REST is that internal models (tables in db or document in mongo) and REST resources must be same. REST resources can be a real model or it can be an abstract entity as well which might not exist in db.
So in this case, your url with POST i.e. POST /products request is perfectly alright as far as REST is concerned. And advice from my personal experience - One doesn't needs to be too dogmatic about url as long as basic principles of REST are conserved such as
Use right HTTP verbs
Use right status codes
Cacheable architecture
Unique indentification of resource by url
Hypermedia (if you can go that far)
I've building a new RESTful API and was looking for clarification. It is ok to use POST to update and PUT to create?
Also, if I try to create an item that can only have one instance in my id (think a list of types), what would my http error code be? 409?
I am new to designing REST APIs. I have trying to create following APIs for online game play
GET domain/api/games // return all games
POST domain/api/games // create a new game on behalf of current user
Now my issue is that when I try to create game using POST, I want userId to be sent to the API. I am not sure how to do this. Also note that I have another get API to get details of individual game, something like
GET domain/api/games/{gameId}
so I cannot pass userId to POST like domain/api/games/{useID} as it will conflict will above API.
So how do I pass usedId to POST. Also I don't want to use query params. Any suggestions to design this would be great.
When you are making a POST to a service, the parameters you communicate are known as BODY params, they don't go on the query string.
Different technologies have different APIs for interacting with POST params, but the underlying theory is the same, and is described by the W3C HTTP standard
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
The specifics of how to use POST params vary depending on the language and technology you're using. For example, if you are using jquery, there are a couple different ways to do it, with with the $.post('url', data, callback) method or with the $.ajax(...) option.
http://api.jquery.com/jquery.post/
http://api.jquery.com/jquery.ajax/
When reading POST params on the server, you'll generally access them using some some sort of request object, that will store your parameters in memory for you to access. This is highly dependent of the language and framework you're using, but here are links to some common ones:
NodeJS/express: http://expressjs.com/4x/api.html#request
PHP: http://php.net/manual/en/reserved.variables.post.php
ASP.Net: http://msdn.microsoft.com/en-us/library/system.web.httprequest.params(v=vs.110).aspx
Java/Spring: https://spring.io/guides/gs/handling-form-submission/
It should be either part of the context (you can pass it through header) or part of the game object. I prefer the context option, the httpheader can contain some auth bearer token so that you can figure out the user on the backend through the token.
Here is an excerpt from an assignment I am currently doing:
Build a dummy app that:
Contains a REST API that operates over a single resource.
Contains a Backbone client that consumes that API and can list, show, create, update, and remove that resource.
My understanding was that the term "consume" implies total coverage of the API's exposed ressources. However, the assignment says "consumes that API and can [CRUD] that resource".
Is that sentence redundant or is my understanding of the term wrong?
(Bonus question: why searching Google for this question returns countless language-specific tutorials for "consuming an API" but none explain what the term actually means?).
To consume an API means to basically use any part of it from your application.
Consuming an API here means creating a client which can send requests to the API that you build.
It appears that you need to create and API which can handle Create, retrieve, update and delete (CRUD) of a resource. For instance if your REST api is to create a blog, your API should handle CRUD functions for the object/resource blogpost.
POST - Create a blog post
GET - Retrieve a blog post
PUT - Update a blog post
DELETE - Delete a blog post.
It is about the direction of the app's interaction with API - it either provides an API, or consumes it, so there are providers and consumers of API, and this is just a less general and ambiguous term than 'using'.
Simply consuming an API means using it in your application.
For, e.g., GET request to https://someapi/Users will give you all the users.
You need to request this URL https://someapi/Users to get all the users and then you can use it into your application.
I always think about Albert Einstein's quote of "If you can’t explain it to a six year old, you don’t understand it yourself." when someone asks a question that you might take for granted due to technical experience you have on a subject.
I think the following medium.com article does an excellent job explaining it: How do you explain API to a 5-year-old?
simply means : using the API.
You can do it with HTTP method (GET, POST, PUT, DELETE..) using something like Postman (Tool) or maybe you have a client app/library that calls these methods implicitly.
I would like to know if there is some best practices about the root endpoint for a REST web service? I mean, should it be a short documentation about the usage of the API itself? Should it be an XML document describing all methods available? Should it only return "unknown method"?
The question is perfectly clear to me.
I think it should respond with 404. If there is no resource associated with the root path, then there is nothing to return.
If you feel that 404 is not helpful, then it would also be OK to return the URL of the documentation.
REST is supposed to be self describing so having the root show an error is poor design in my opinion.
I like the root to contain information that allows you to navigate the rest of the API.
So for example the root might contain a link to a list of product categories from which the API user can select a category and then a list of products etc.
A self describing API means less documentation to write and keep updated!!
NerdDinner.com1
The Sun Cloud API
Twitter
Paul Jame's article
MediaWiki's API2
1. NerdDinner uses WCF Data Services, which is a great way to correctly implement RESTful services. The reason I am point to that, and not WCF data services directly is because it is a public website and you can use it.
2. MediaWiki is not a great example because they are passing actions in the URI but it is technically a RESTful service and show's a lot of interesting ideas.
This question as asked is unclear. I would guess it means something like a directory that all API methods are under. For example, the root directory of the Flickr API would be http://api.flickr.com/services/rest/.
For an example of a project that accesses the Flickr API, see python-flickrapi
the rootend point of REST API is the the API defined for the first slash i.e "/" of the url after the dispatcher-servlet. It contains all the GET for the list of resources (mostly the get for all the database tables) this list further contains all the items and in single item there will be DELETE , PUT/PATCH and SELF get URL. Thus making the implementation of HATEOS.
For me, I just redirect to my frontend.
In node JS, use res.redirect("https://<<your frontend>>");