I want to know what’s the difference between a web service (web api) and a rest api
I have learnt till now only GET and POST methods in backend to communicate with my apps but people always talk about PUT DELETE UPDATE & REST etc I am unable to understand the benefits and meaning.
What is the difference between a rest api and web api
Neither of these terms is well enough defined to assert with any confidence "the" difference.
REST is an architectural style; the most important application of that style is the world wide web. The web has been so catastrophically successful that there really hasn't been a second REST application - if you need what REST offers, you use the web, because the hard work has already been done for you.
I am unable to understand the benefits and meaning.
For every standardized HTTP method, you can use the HTTP method registry to find the reference that defines the meaning of the method.
Most of the methods that people talk about on a regular basis have their meanings defined by RFC 7231.
The benefit comes from the fact that the meanings of the different methods are standardized; the provide certain semantic guarantees that allow general purpose components to do clever things.
For example, knowing that a method has idempotent semantics means that we can resend the http request when we don't get a response the first time, this is an important constraint when your network is unreliable. Because that's true of all idempotent requests, regardless of which URI is being targeted, we can build a retry into the browser.
It may help to think about POST as "the" basic message, and all of the others as being specializations
GET is a specialization of POST that is used to retrieve copies of representations
HEAD is a specialization of GET that is used to retrieve metadata
PUT is a specialization of POST that is used for "upserting" new representations
PATCH is a specialization of POST that applies patch documents to a resource
Related
We have our API versioning strategy based on URL.
I have couple of scenarios to add new enpoints , where I could not find any strategical reference for this.
Scenario 1:
An existing API having endpoints varyingly ranging from versions v1 to v4. Few endpoints are upto V2, few are upto V3, and few at v4.
In this situation If I have to add a new endpoint, Should I begin the version for the new endpoint at V4? Is there any standards for it.
Scenario 2
This is the different scenario. one of the API GW spanned across multiple microservices, and the micro services are grouped by resources within the gateway. so a resource have a one on one mapping against a service.
Similarly different API versioning exists btw resources here. Few resources were upto V3 and few are up to v5. if a new endpoint is required to be added to a resource which is already upto v3, should we add a new endpoint in v3 or should we create a v5 version of resource to add that specific endpoint?
Any suggestions would be helpful.
You're unlikely find a standard way of doing things. The closest thing to a standard is what Fielding and the HTTP specifications say themselves. You should expect these questions to enlist many subjective opinions. Here's my bias opinion based on experience and a deep understanding of the specifications...
Conceptually, there's no real problem with adding new endpoints to an existing API. Where this might be problematic is if your API is public and with public documentation. Once an API version is released, it should be immutable so that clients can rely on it. If you're adding surface area to your API, then I would recommend you create a new version. If you're unsure what that version will shape up to be in totality, you can always start with a pre-release version; for example, 4.0-preview.1.
Your second question seems to ask whether you should have symmetrical versions. You can, but it's solely at your discretion. You indicated that you have microservices, so unless you are building out an API for an entire product or suite, it is more flexible to allow an API to evolve independently. This will organically result in heterogenous API versions over time. That shouldn't be a problem IMHO. The key to making that manageable is to define a sound versioning policy, such as N-2 supported versions.
You've already elected to version by URL segment, so there's no going back. Versioning this way leads to a spider web of different URLs when the versions are not symmetrical. This is just one of the many problems you may encounter. Hypermedia is almost all but impossible to achieve when versioning by URL unless the versions are symmetrical. Ultimately, versioning by URL segment is not RESTful, despite being popular, because it violates the Uniform Interface constraint. The URL path is the resource identifier. v3/order/42 and v4/order/42 are not different resources, they are different representations. In the same way, I can ask for order/42 as application/json or application/xml, but they are not different API versions, even though they look completely different over the wire.
As an example, if you retrieve v2/order/42 and it has a link to customer/42, but the Customer API supports 2.0 and 3.0, how do you know which link to provide? If the client only knows how to talk v3/customer/42 and you give them v2/customer/42, it might break them. Furthermore, what happens if the Customer API doesn't support 2.0 at all? The Order API has to incorrectly assume v2 is a valid or it has to be coupled into knowing which versions are supported; both of which are not good. In all cases, the server still doesn't know what the client really wants. It is the client's responsibility to tell the server what it wants. Every other method of versioning does not have this problem as the URLs are always consistent. Let's say you version by query string with api-version, another popular choice. If you provide a link to customer/42, the link is valid regardless of API version. It's the client's job to know and append ?api-version=<value> to indicate to the server how they want to query the resource. This is why Fielding says that media type negotiation is the only way to version an API. It's hard to argue with the G.O.A.T., but using the query string or another header doesn't explicitly violate any constraints, even if media type negotiation would be better.
I have been trying to wrap my head around this and I'd appreciate if someone could enlighten me.
What is the main difference between making a "HTTP GET" request to a webpage and fetching the HTML VS making "HTTP GET" request to a REST API endpoint and fetching JSON?
As far as I know, REST API can also return HTML, so in that case, what would be the main differentiator between these two?
I may be missing something obvious here but I am just trying to conceptualize each action so I have no more ambiguity.
Thanks in advance.
What is the main difference between making a "HTTP GET" request to a webpage and fetching the HTML VS making "HTTP GET" request to a REST API endpoint and fetching JSON?
Not much?
In the REST architectural style (which is followed by HTTP... mostly). an important constraint is uniform interface, which includes the idea that all resources understand all messages the same way.
That means we can do things like use a general purpose web browser to fetch documents, or a general purpose cache to store representations, without needing any special code to distinguish "web resources" from "api resources".
A "good" REST API looks like a machine readable web site.
The only difference that you might notice in some cases is that the hypermedia representations of resources might use some standardized format that isn't HTML.
Otherwise, they are the same thing - the main difference being that a "REST API" tends to have more resources that are expected to be changed by incoming requests, as opposed to a website which is designed more for reading than editing. So PUT/POST/PATCH requests are more commonly used with API resources.
I'm new to this game so I might be misunderstanding things. Actually, if someone tells me that I'm misunderstanding things, it will be a favor. Maybe this person will be considerate enough to show me the right path. But...
One of the "guidelines" or "best practices" of REST as it applies to Web Services (http://en.wikipedia.org/wiki/Representational_state_transfer#Applied_to_web_services) is that you should use the proper HTTP methods when making calls (did I misunderstand it?) to REST API's.
But looking at many API implementations on the web, what I see is that 100% of the calls made to them are actually GET calls that, depending on their URI, will be interpreted by the API as being of one of the HTTP verbs or methods.
So, for example, looking at the REST API documentation for Twitter (https://dev.twitter.com/rest/public) which, in principle, only defines two verbs/methods (GET and POST), actually have all calls sent as GET and, based on the URI in the GET call, are interpreted by the API and acted upon.
Example:
GET statuses/lookup: https://api.twitter.com/1.1/statuses/lookup.json
POST statuses/update (PUT?): https://api.twitter.com/1.1/statuses/update.json
In both cases, the call itself was made using GET and the last part of the URI defined it as a real GET or as a POST.
In summary, to be truly RESTful, shouldn't client side implementations of REST API's for web services use the proper HTTP verbs/methods?
What am I missing?
You're missing a lot, but don't worry about it, most people are.
The fact is that very few so-called REST APIs publicly available on the internet are really RESTful, mostly because they are not hypertext driven. REST became a buzzword to refer to any HTTP API that isn't SOAP, so don't expect for an API to really be RESTful just because it says it's a REST API. I recommend reading this answer.
From my experience, most API developers aren't aware what REST really is and believe any HTTP API that uses HTTP and avoids verbs in URIs is REST.
REST is defined by a set of constraints. Among them is the uniform interface, which in simple terms means that you should not change the expected behavior of the underlying protocol. REST isn't coupled to any particular protocol, but since it's common to be used with HTTP, they get convoluted sometimes.
HTTP has very well defined semantics for the GET, POST, PUT, DELETE, PATCH and HEAD methods, and the POST method has its semantics determined by the server. Ideally, a REST API should respond to the methods other than POST exactly as determined in the RFC 7231, but as you noticed, there are many APIs who call themselves REST but don't do that. This happens for many reasons. Sometimes there's a simple misunderstanding about the correct semantics, or it's done to keep consistency, or because of backwards compatibility with intermediaries that don't support all methods, and many other reasons.
So, there's a lot more that has to be done to be truly RESTful other than using the HTTP methods correctly. If an API doesn't get even that right, it needs to find another buzzword, because it's definitely not REST.
I can't exactly tell what your question is, but I believe there are some concepts that will help you. Allow me to elaborate...
You are correct that many APIs use a limited number of HTTP "verbs" in their API. GET/POST are the most common. PUT less so, and then all others (DELETE, HEAD, OPTIONS etc) are used with vanishing probabilities.
Dropbox Core API for file uploads allows optional PUT / POST and their stated reason is "For compatibility with browser environments, the POST HTTP method is also recognized."
Indeed the limitation is the browser. Popular web servers have no problem with all HTTP request methods and even made up ones. After all, the request method is just some string with regard to the web server.
HTML4 and HTML5 only allow GET and POST requests for form requests. If you want your API to be used through a browser at all - and hey why not, it sounds like a useful thing - then you're limited to GET/POST. For a useful discussion on this see: https://softwareengineering.stackexchange.com/questions/114156/why-are-there-are-no-put-and-delete-methods-on-html-forms
Further complicating things is the fact that REST is not an industry standard. There exists no RFC, ISO or other document detailing what a "compliant" implementation must and must not do. While many folks have been playing concepts related to REST for some time, the REST concept was "invented" in the PhD disseration of Roy Fielding. A fantastic read if you're interested in such things.
Yes, according to REST, APIs should be using the correct verbs. However, as long as the documentation is clear and all GET requests are idempotent, then life should continue smoothly.
(Source: I wrote PipeThru.com which integrates 40+ APIs, Dropbox and Twitter included)
I think that this link could give you some hints about the design of RESTful services / Web API: https://templth.wordpress.com/2014/12/15/designing-a-web-api/.
It's clear that not all Web services that claim to be RESTful are really RESTful ;-)
To be short, RESTful services should leverage HTTP methods for what they are designed for:
method GET: return the state of a resource
method POST: execute an action (creation of an element in a resource list, ...)
method PUT: update the complete state of a resource
method PATCH: update partially the state of a resource
method DELETE: delete a resource
You need to be also to be aware that they can apply at different levels, so methods won't do the same things:
a list resource (for example, path /elements)
an element resource (for example, path /elements/{elementid})
a field of an element resource (for example, path elements/{elementid}/fieldname). This is convenient to manage field values with multiple cardinality. You don't have to send the complete value of the fields (whole list) but add / remove elements from it.
Another important thing is to leverage HTTP headers. For example, the header Accept for content negotiation...
I find the Web API of Github well designed and its documentation is also great. You could browse it to make you an idea. See its documentation here: https://developer.github.com/v3/.
Hope it helps you,
Thierry
You are correct. If they want to be "RESTful", their API should respect the semantics of each HTTP method.
Roughly, REST is about method Information (what the server should do), scoping information (where the server should do it) and, I almost forgot to mention, hypermedia driven (make sure you check #PedroWerneck's great answer to this question as it talks about it a little more and referecences a blog post from Fielding on the matter).
What the API you mentioned does is have both method and scoping information in the URL. That would not fit the RESTful architecture very well, as it, in general terms, tells us to:
1) use the HTTP methods the proper way (respecting their properties, such as idempotency and others), and
2) use unique URIs to identify unique resources.
Point 1 says "use HTTP methods to convey method information" and point 2 says "use URIs to convey scoping information".
Again, if an API uses GET with a specific parameter in the URI to do something (and not get something), then it is using URI to convey method information.
Now, don't be alarmed. Most APIs out there are just RESTful-ish (like twitter's of flickr's), meaning they are an animal between REST and something else. That is not bad per se, it just means they will not fully benefit from what RESTful architectures (and HTTP) have to offer.
Remember that being RESTful isn't just a matter of fashion, it does have its benefits, such as statelesness, adressability, and so on. And those can only be fully achieved by using the HTTP verbs like they were supposed to be used.
About using POST instead of PUT, considering they have different properties (PUT is idempotent, POST is not), it is not bad to use POST, as long as it is uniformly designed, that is, a programmer should not wonder what POST will do for each and every URI in the API: they all should behave the same. (PUT does not suffer from that because it already is uniform.) I talked a little more about this - and quoted Roy Fielding's say on it - in another question (check out the "Wrapping Up" part).
Consider looking at REST Richardson Maturity Model topic.
This specification is about how much RESTful particular API is:
Level 0:
Simple GET and POST request to descriptive url
/getUserByName?name=Greg
Level 1:
Divide all content in resources and define actions in resource group
/user/getByName?name=Greg
Level 2:
Proper use of HTTP verbs.
GET /user/Greg
Level 3:
Use hypermedia controls
Different APIs in interent implement different maturity level of REST. That's why some APIs don't support all HTTP features.
What things should a developer designing and implementing an API for a community based website know before starting the heavy coding? There are a bunch of APIs out there like Twitter API, Facebook API, Flickr API, etc which are all good examples. But how would you build your own API?
What technologies would you use? I think it's a good idea to use REST-like interface so that the API is accessible from different platforms/clients/browsers/command line tools (like curl). Am I right? I know that all the principles of web development should be met like caching, availability, scalability, security, protection against potential DOS attacks, validation, etc. And when it comes to APIs some of the most important things are backward compatibility and documentation. Am I missing something?
On the other hand, thinking from user's point of view (I mean the developer who is going to use your API), what would you look for in an API? Good documentation? Lots of code samples?
This question was inspired by Joel Coehoorn's question "What should a developer know before building a public web site?".
This question is a community wiki, so I hope you will help me put in one place all the things that should be addressed when building an API for a community based website.
If you really want to define a REST api, then do the following:
forget all technology issues other than HTTP and media types.
Identify the major use cases where a client will interact with the API
Write client code that perform those "use cases" against a hypothetical HTTP server. The only information that client should start with is the response from a GET request to the root API url. The client should identify the media-type of the response from the HTTP content-type header and it should parse the response. That response should contain links to other resources that allow the client to perform all of the APIs required operations.
When creating a REST api it is easier to think of it as a "user interface" for a machine rather than exposing an object model or process model. Imagine the machine navigating the api programmatically by retrieving a response, following a link, processing the response and following the next link. The client should never construct a URL based on its knowledge of how the server organizes resources.
How those links are formatted and identified is critical. The most important decision you will make in defining a REST API is your choice of media types. You either need to find standard ways of representing that link information (think Atom, microformats, atom link-relations, Html5 link relations) or if you have specialized needs and you don't need really wide reach to many clients, then you could create your own media-types.
Document how those media types are structured and what links/link-relations they may contain. Specific information about media types is critical to the client. Having a server return Content-Type:application/xml is useless to a client if it wants to do anything more than parse the response. The client cannot know what is contained in a response of type application/xml. Some people do believe you can use XML schema to define this but there are several disadvantages to this and it violates the REST "self-descriptive message" constraint.
Remember that what the URL looks like has absolutely no bearing on how the client should operate. The only exception to this, is that a media type may specify the use of templated URIs and may define parameters of those templates. The structure of the URL will become significant when it comes to choosing a server side framework. The server controls the URL structure, the client should not care. However, do not let the server side framework dictate how the client interacts with the API and be very cautious about choosing a framework that requires you to change your API. HTTP should be the only constraint regarding the client/server interaction.
My idea is to treat URI's in my rest api as a unique resource, except in the context of the client's location, which is stored in a cookie. Are there any downsides to this approach?
From a philosophical perspective, it's not really REST if you don't uniquely identify the resource via URL (at least, per my reading of Fielding).
From a practical perspective -- and this is based on experience -- you're in for a world of pain if you require web service calls to use cookies. Primarily because it's a piece of information that has to be managed on a different code path, making your client-side code more complex. You'll also run into issues with domain and proxies (particularly if you share the cookie between the service and a traditional web-app), and it isn't portable between clients.
If you're looking to generate different content based on location, why not use a geolocation service?
Edit: why not make location part of the request URL? You can still use a cookie to store this information, and retrieve it using JavaScript. This would leave your service interface clean, and allow you to easily use the service from other clients.
As an API, you should aim at making ease of use for the client programmer a high priority. In many libraries that support HTTP, putting cookies into the HTTP request is more difficult than putting, say, a query parameter into the URL.
I'd be concerned about caching. Do one request with the user at location A, it gets cached, user moves to B and makes the request again, gets location A version of the request.