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?
Related
I am creating API and trying to figure out is planned approach any good.
That API is not public and it will be used by SPA and mobile app that I build.So I am thinking of GraphQL-like design but without posting json and with regular HTTP methods.
Something like this for GET methods:
Example 1 - get users with specific fields(_join indicates sql table join), ordering and limit:api.com?table=users&displayFields=id,name,email,address,tel,country_join&orderBy=asc&orderColumn=name&offset=0&limit=10
Example 2 - get users based on search parameters with all fields, ordering and limit:api.com?table=users&search=John&searchFields=name,email&orderBy=asc&orderColumn=name&offset=0&limit=10
I assume this is bad since REST is standard, otherwise I would see much more examples of this approach.
But why is this bad? For me it seems easier to develop and more flexible to use.
Is proper REST API for examples I provided easier to implement, safer, easier to use or cache?
The main difference I see between putting the variables in the url vs the request body are:
the length of the data as the url length is limited while the request body is not
special characters to be escaped in the url which can lead to long and unclear url
These are 2 pros in favor of data in request body, but I agree that data in url is much simpler to test and use as tou don't need an http client tool like curl or postman to validate your endpoints.
REST however has stricter conventions if you want to fully implement it:
use the right http requests (get, post, patch, delete and put) to implement crud operations on one single endpoint
return the right http code as a result
use standard data format for input and output (json or XML)
For better interoperability between systems it's advised to comply with REST and microservices design patterns.
For small applications we can follow some shortcuts and not comply fully. I have integrated several services so far and each time I can tell you no one of them implements standard REST :-)
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.
We are creating a RESTful API (PHP on apache server) which will communicate with an Android application. Im new for this so excuse me if my question is dumb.
I want to ask for data from the api so I need to use GET method in the request taking into account the semantics. I have to send some additional data to specify what data am I requesting. In GET requests, I cannot send form data fields so how should I attach the data?
Using POST (but this is not semantic)
request header: POST http://example.com/api/v1/serials
request data: date_from=2013.01.01&date_to=2014.01.01&userid=112&is_in=0&starts_with=afx00
using GET and adding url params (I don't know if is this a good practice in a REST API)
request header: GET http://example.com/api/v1/serials?date_from=2013.01.01&date_to=2014.01.01&userid=112&is_in=0&starts_with=afx00
or making well formed URIs with no url params in GET (not sure about this as well.)
request header: GET http://example.com/api/v1/serials/date_from/2013.01.01/date_to/2014.01.01/userid/112/is_in/0/starts_with/afx00
Which one fits the best in the RESTful API architecture? Which should I use and why? Or maybe are there any other options for what I want?
Without question using URL parameters is best. It allows consumers to query for serials using their choice of filters. Your API should support returning results based on UserId alone, or a date range, or both. Or other combinations of inputs that make sense.
Embedding the key/value pairs of the filter in the resource path is an anti-pattern. It's difficult to understand what each path element means, and you would need to contort your routing engine to accommodate additional filter criteria. It also provides no flexibility in terms of choosing what filter criteria to use - you would in fact need to construct multiple resources paths for each combination of filters. And there is the management of ordering each pair (with URL params, ordering doesn't matter). Probably more reasons to avoid this, but those are the first that spring to mind.
Bot GET methods can be used. It is your choise. But I'll prefer using url params. It is easier.
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>>");