I am currently working on Rails.I have read a lot of documents regarding REST api and RESTFul routes.But i am unable to figure out the relation between these two.My understanding for RESTFul routes is that a http verb is associated with them and i found out nothing else.
Can someone please make these things clear?
1.What are RESTFul routes and their benefits?
2.In what way RESTFul routes are co-related with Rest Api?
3.What are the benefits of REST api over SOAP api?
I don't know Rails, but I can tell you the following:
1)The routes are defined in order to map an incoming request to a controller action. A request is made of an HTTP method (GET/PUT/POST/DELETE), an URL and possibly some content in the body. For example GET books/1234 is a RESTful request for the book identified by the ISBN 1234. A framework like Rails has to map this request to a controller action. Such an action is an operation whose name is a verb. In the router you have 2 main components for an entry: the request and the mapped action. For example, in get '/books/:isbn', to: 'books#getBookByIsbn' what you say is that a GET request with an URL matching the given structure will be mapped to the action called getBookByIsbn from the controller books.
2)One benefit of RESTful services is that IMHO they are simpler, easier to user than SOAP/WSDL based services.
Related
I have seen sometimes in applications when you're doing a get request for example, URL is:
www.baseurl.com/thing/{{ID}}
Sometimes there is no representation of the restful action in the URL. In my current job for example, the URL never changes. This is probably because we are not following single page application principles.
So on a get the URL would not change at all, and would be either:
www.baseurl.com/
Or
www.baseurl.com/thing
A few questions:
What is the architectural pattern name for the URL with the ID in it?
Is it RESTful?
What are the pros and cons?
If it's RESTful what are the benefits to doing it this way, across http requests?
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 have read a few articles about HATEOAS and the way that API should be implemented such that you can traverse to different states by following the links. But I'm confused as to how the client should be implemented?
From this answer:
The client knows nothing about how the server designs its URIs other
than what it can find out at runtime.
Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?
What would be the purpose of API documentation then?
For implementing HATEOAS server needs to include links to responses that goes from server to client, and client uses these links in response to communicate to server.
For eg. Client request Product list, server will respond with list of products with link to Add, edit and delete the products (if user is able to do that), which will then be transformed in client into links or buttons like Edit Product, Delete Product.
This blog might help you get more understanding.
Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?
Yes unless the root page does not contain the link which describes the POST.
What would be the purpose of API documentation then?
It describes the metadata the client can recognize for example by a link or by a property. So it describes the capabilities of the service.
To answer your first question "Does the client need to crawl from the root node down to a nested resource to just make a POST if it doesn't know the direct URI?"
The answer is No. The client always does not have to crawl from the root node. It is possible to design the URI;s such a way that the navigation to reach the direct URI can be from other views. For example if the purpose of the URI (/Products/product1/Delete) is to delete product , then it should be possible to reach this by either crawling from the /Products or by giving a namespace query of Products/Deleteview. This "DeleteView" URI should give all the URI's of the delete view. i.e it can return a uri collection like Products/product1/Delete, Products/product2/Delete etc.
To your second Question "What would be the purpose of API documentation then?"
Concept of API is a legacy of the past. Ideally the URI itself should be the documentation. This way the client can be programmed to discover and take only things that it can respond to.
We got hold of unique technology which manages these namespaces. so we are shielded from this view manipulation ourselves. I recommend using a technology to manipulate and create these URI namespaces.
Is it true that to implement a RESTful API, one has to implement a URL structure that looks like this
http://example.com/post/
http://example.com/post/123
where the /123 would be used for edit, delete
Another way to ask the question is: can a URL that looks like this be called RESTful?
http://example.com/script.php?method=get_title&blogid=123
You don't have to design your URI structure like that. It could also be /some_obscure_string/base64_encoded_title/unique_id. This could also be RESTful, depending on several other factors.
But there are several best practices on how to design URIs in a RESTful web application and being as simple and as human readable as possible is one of them.
Your example http://example.com/script.php?method=get_title&blogid=123 could also be RESTful, but the query parameters indicate that some kind of RPC- or RMI-over-HTTP is used instead.
To sum it up: Don't put too much thought into your URI design. This will come automatically with a good and proper RESTful design of your application.
The Idea behind REST is that every resource has it’s own URL and you use the different HTTP methods to interact with those resources. It makes sense to define the URL structure so that the hierarchy between different resources is reflected in the URL, but you don’t have to.
If you have URLs like this
/all-posts/
/first-post
/some-stuff/second-post
/third-post
you still could provide an RESTful API to this. The Idea is that a GET to /all-posts/ returns a list of the URLs of every post object and the client uses those URLs to interact with the resources. Basically the URLs should be treated as opaque data by the client.
As long as the URL that is embedded in the client doesn’t change you also could change the structure without having to change the client.
Your example URL probably doesn’t belong to a RESTful API, since it contains a method get_title. In REST a URL represents a thing. What is to be done with the thing (should it be modified, should it contents be retrieved, ...) is not part of the URL, for that REST uses the different HTTP methods.
A key aspect of REST is that the url is the resource. a uri like
http://example.com/script.php?etc-etc-etc
doesn't put the resource identifier in the resource portion of the uri. that's not to say that a RESTful API shouldn't ever use get parameters; in fact, that's just fine:
http://example.com/posts?sort=date_asc&offset=20&limit=10
might be a great way to get the URI's of the 3rd page of oldest posts. However, using get parameters in this way should only be used in requests where the method is also GET. PUT and especially POST methods should really use simple uri's with the resource that will be affected in only the path portion.
RESTful URI design is all about resources access and they should be structured in the RESTful manner, so you should not have any query strings.
e.g. of GET
authors/
authors/1
authors/1/books
authors/1/books/10
authors/1/books/10/summary
etc.
Anything and everything is called RESTfull these days, just look at some of the responses by it's inventor Dr Roy Fielding and you'll get some ideas. It is worth doing some reading on the subject.
P.S you do not need post,get etc in your URIs, HTTP protocol is at present mostly used for consuming REST APIs and you can pass verb as a part of the call. Also there is a concept of content negotiation i.e you can request any available format from REST API (json,xml atc).
The REST concept is really based on the fact that it is URL driven, and not driven by large data-blobs. With REST, you don't have to pass a giant soap request to invoke a method - your method call/object creation/whatever you want to do is invoked simply by the URL, and the verb you used vs that URL.
Example URLs:
GET http://del.icio.us/api/
GET http://del.icio.us/api/peej/tags/
GET http://del.icio.us/api/peej/tags/test
DELETE http://del.icio.us/api/peej/bookmarks/[hash]
The structure of your URLs doesn't matter. What does matter is that each URL identifies exactly 1 resource. Each resource can have multiple URLs that point to it but each URL should only point to 1 resource.
This can be helpful. Ref:
RESTful service URLs
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>>");