REST is used to communicate any two systems.
So that if you want get info from one machine we have to use GET method and add info in one system we need to use the method POST..Like wise PUT and DELETE.
When a machine GETs the resource, it will ask for the machine readable one. When a browser GETs a resource for a human, it will ask for the human readable one.
So When you are sending request from machine 1. It will go to some machine x. Machine x will send a machine readable format to machine 1. Now Browser changes to user readable format.
So JSON is a machine readable format and HTML is a client readable format...Correct me if i am wrong?
REST is an architectural style, not a technology. That being said, the only technology that most people know that is intended to align with the REST architectural style is HTTP. If you want to understand the REST architectural style, I recommend the following two resources:
Roy Fielding's presentation "The Rest of REST" (http://roy.gbiv.com/talks/200709_fielding_rest.pdf)
The book "RESTful Web Services"
When you send a GET request for a resource, it is up to the server to determine what representation (format, e.g. html vs. json) it wishes to send back. The client can send along an Accept header that specifies a set of preferred formats, but it's ultimately up to the server to decide what it wants to send. To learn more about this interaction, Google on "HTTP content negotiation".
The reason browsers tend to get back HTML is that they send an Accept header with "text/html". If you somehow configured your browser to always send an Accept header of only "application/json", you would sometimes get JSON back (if the server supported JSON representations), sometimes HTML (if the server ignored your Accept header) and sometimes an error saying that the server could not support the representation you requested.
A computer can parse either JSON or HTML if you have the right libraries. JSON content tends to be structured data (optimized for parsing) and HTML tends to be optimized for presentation, so JSON is generally much easier for a program to parse.
Sounds about right to me. HTML is definitely for end-user consumption (despite all the nasty screen-scraping code out there) and there's no way that I'd want to deliver JSON (or XML or YAML) to end-user clients for direct display.
You probably want to ensure that you only deliver HTML that matches up with the same basic data model that you're delivering to mechanical clients; producing XHTML on demand by applying an XSLT stylesheet to an XML version of your standard responses is probably the easiest way to do it since it's likely you can do that with a layer that's independent of your basic application.
To be pedantic, both HTML and JSON are machine readable formats. The difference is that HTML has a specification that describes some semantics that web browsers know how to interpret in order to visually render it. The JSON spec has really no semantics other than defining how to serialize arrays, objects and properties.
Don't forget JSON and HTML are just two of the hundreds of potentially useful media type formats that a RESTful system can use.
Related
I'm new to web services world. I have created a rest api in ERP software that creates sales order. How will anyone outside the world know what parameters to send to this and in what format ? From all the videos I have watched and all materials read they talk about no api documentation is needed as it is REST service, People just know what request payload to send. I m not sure if I understand how that is possible. Its like I give somebody the url and tell them go figure. I tried sending orders with different parameter list and it is creating errors. But, if I send it in the way it accepts then it is working fine. Not sure if I understand the concepts well. Should I be creating documentation of this api telling what the request payload should look like ?
I completely disagree with the answer given by Joessel, which just propagates a typical RPC take on it, which is NOT REST at all!
In regards to how a service utilizing the REST architecture style should inform clients about what properties a resource supports and stuff like that, just look at traditional HTML pages. How are Web server able to tell your Browser what input it expects?
HTML is a media type that specifies the syntax to use as well as the semantics of each of the elements and attributes wich are admissible in a HTML document. I.e. HTML Forms enables a server to inform a client on the respective properties a resource support. In addition to that, a server also teaches a client on the respective target URI to send the request to, the HTTP operation to use upon sending the request as well as the media type to use for marshalling the request to a respective representation format. This is why you DON'T NEED any other documentation to interact with Web pages. Most arbitrary Web clients support HTML documents by default and therefore you don't need to reimplement the wheel to process such documents.
For non-HTML resources it is also just a matter of whether your client supports the respective media type or not. I.e. PNG files also follow a certain standard which allows arbitrary clients to show images instead of the actual bytes on your screen.
Most of those so called "REST APIs", which are truely RPC ones, just use custom JSON based message structures. JSON itself just defines the basic syntax but no semantics for any elements, attributes or other properties. It doesn't even add support for links. JSON Hyper-Schema is an extension which at least triest o add support for it, though it already requires to use an other media type than application/json. Though, if such formats are not well-defined and standardized, widespread adoption will not be possible on the long run. Hence creating a common media type is of importance to increase interoperability for such media types. I.e. for JSON based formats, HAL+JSON, HAL Forms, ION, and others provide definitions for basic JSON based message structures, with support for links and other features like form-support and other things.
So, if you take a closer look at the Web, you will find many concepts that you can reuse for a truely RESTful design. After all, REST just takes the ideas used on the Web for decades and attempts to offer the benefits resulting from these concepts to applications rather than humans alone. As such, it is always a good idea to first design the interaction flow as if one would interact with a traditional Web page and then take the concepts used in that design and apply it onto your application domain model.
As you don't need external documentation to interact with Web pages, so you don't need external documentation to interact with well defined message formats that follow a common media type as well. Through content-type negotiation both server and client will communicate with representation formats both support. So, the more (different) media types you support, the more likely you will be in the end to interact with different parties in that environment and if all of the supported media types are standardized you might not need any external documentation at all.
If you follow the academic definition of REST defined by Dr Fielding in his dissertation, it is true that such a service doesn't need any documentation. Hovewer, the chance are high that your service is not RESTful by his definition and that you need a documention to help your consumers. You can find an informative discussion about why a REST api doesn't need a documentation here.
That being said, you will probably need a documentation in most case. Depending on your needs and consumers of your api, a simple text file could be enough; maybe a markdown that you can easily share with other developers. Just remember to add all information needed to understand each route (verb, path, query, body, response...), and you can even throw some example code to make it easy to start.
And if you need something more robust, I can only advise you to follow the open api specification. One of the easiest way to get started is to use the swagger editor . You will even be able to publish your documentation in a nice way using one of the many tools out there (ex: redoc).
Writing a documention is never fun but nobody will use a product that they cannot understand, however great the product is.
Good luck,
Edit:
I rewrote the introduction as it was misleading, thanks to #Roman Vottner for pointing it out. THe previous intro was:
I don't know who told you that a documentation is not needed for a REST Api but I find this highly misleading for newcomers... A documentation is (super) important, especially if you are not the sole consumer of your API, and in that case I would say it's mandatory.
A few times I have come across a problem where I need to create a RESTful-API, but the requirements also states that "it should be possible to upload a file using the API"..
The past few times I have solved this by simply allowing the client to send a multipart/form-data with the content of the file to my RESTful-API.. however.. thus approach sort of makes me wonder if this is the right way to do it.
The RESTful-guidelines clearly states that you should only be able to CRUD for ONE single resource, but the nature of a multipart/form-data is multiple resources (for instance, 1-many files.. or 1 file and a bunch of metadata, etc). Now I can either just simply limit the endpoint to only allow one single "content" within the multipart/form-data and then associate that with the correct url, but that would sort of break the purpose of a multipart-content-type.. or I could allow the C(R)UD-operations of multiple resources, or I could treat the whole request as one single resource (one resource that contains a file, metadata etc.. however, for a GET it would not be possible to get the same response as the content sent during the request, since as far as I know you cant GET a multipart/form-data, but you could get a single file, or a single JSON/XML etc..)
Has anyone solved this in a "neat" way that complice with both REST and doesnt limit multipart to be one single "resource"? Or should I simply not use multipart and use something else for files, and in such a way be able to seperate file uploads and "text/json/xml/etc-uploads"?
REST is an architectural style.
The dominant application designed with the REST architectural constraints is the world wide web.
On the web, a common way to upload a file is to use an HTML form, with the enctype set to multipart/form-data, and also an input control with type=file.
Any general-purpose component will know the right thing to do, because all of the useful bits have been standardized - the hypermedia representation of the form (provided by the server) defines all of the parameters the client needs to construct the appropriate HTTP Request.
The RESTful-guidelines clearly states that you should only be able to CRUD for ONE single resource
REST suffers from a lot of semantic diffusion. It can make things really confusing when you start trying to combine ideas from different authors.
REST doesn't mean CRUD -- REST means that all resources understand messages the same way.
HTTP (again, conforming to the REST constraints) defines a number of different methods for clients to use when communicating intended semantics to the servers. For remote authoring semantics GET, PUT (PATCH), DELETE are all we need to communicate remote changes to documents, but HTTP's uniform interface doesn't stop there -- we have a lot of other methods with standards.
And of course, that list includes POST, which doesn't mean "CRUD". The actual meaning is much closer to these semantics aren't worth standardizing.
I'm designing RESTful resources for accessing media. Media could be a live stream or archived stream. I'm using O'Riellys text "RESTful Web Services' as a guide but I'm struggling with the representation of resources relative to the 'programmagable web' versus the 'human web'. For human web request I'd like to return an HTML representation. For programmable web requests I'd like to return XML. That being said, consider:
GET http:// localhost :8080/stream - returns a list of streams
GET http:// localhost :8080/search?stream=abc - return a specific stream
How do I differentiate between a request from the 'human web' versus the 'programmable web' such that I could return the right representation?
O'Reillys text seem to suggest design of two seperate resources. From page 24 of the PDF he states:
I’d use the same tools to fetch and process a web page.
These two URIs:
1) http:// api. search.yahoo.com/WebSearchService/V1/webSearch?appid=restbook&query=jellyfish
2) http:// search.yahoo.com/search?p=jellyfish
point to different forms of the same thing: “a list of search results for the query ‘jellyfish.’”
One URI serves HTML and is intended for use by web browsers; the other serves
XML and is intended for use by automated clients.
Are two separate resources for dealing with the human web versus programmable web the norm or is there alternatives? Thoughts welcomed.
I'd say the official "fielding compliant" answer is to use content type negotiation using the ACCEPTS header. Lots of good stuff at http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
If the client requests text/html, feed the human readable html. If the client requests text/xml, feed it xml. The trick here is that pragmatically this isn't always well supported by the clients, so you'll often need a bunch of fallbacks using query strings or resource name mangling, as in the example you posted.
Personally, I try to follow ideology as long as I can, and then start adding fallbacks pragramaticly as necessary. I wouldn't create a separate resource for programmatic or human consumption until you run into a client that can't properly handle sending an accept header.
Your example doesn't match the question, so I will answer both.
In the example you give, you have two different resources: a list of streams, and an individual stream. As such they should be allocated separate URIs, and I would strongly recommend against using the query string for that where there is a clean and obvious alternative.
In this case it is classic ReST. /stream/ is the Resource consisting of the list of available streams, this list should be presented as a either a human or computer (or preferably both) list of URIs so (as text/html):
<ul>
<li>ABC</li>
...
</ul>
This leads to your next question, how to identify the different Representations of the stream-list Resource. There are three techniques I have used: content negotiation, format query param, and RDFa.
RDFa is my preferred alternative, in this case you only have one representation that encodes both human and machine readable content. In the case of a simple list this is a trivial change to your HTML:
<ul>
<li><a rev="rdfs:member" href="/stream/abc">ABC</a></li>
...
</ul>
If you have one or more pure machine serializations of your data then there are two alternatives I have used; generally, both at the same time.
Content negotiation is the purest, and most convenient. Just have one text/html, and another application/xml or application/json, and let the client choose.
This isn't as convenient when testing the machine version from a browser, command line (curl/wget/etc), or a script. So I like to also support a format query parameter. For convenience sake, have it take a mime-type.
I prefer to have my resource handled by the same controller/servlet/etc, have it fetch the information from the filesystem/database/whatever, and dispatch it to the appropriate view based on the mime-type (content neg or format param) for display. Either way you are dealing with different representations of the same resource, so it is a good idea to ensure they are available from the same Base URI, whatever alternative approaches you decide to support.
This is a follow up on a question asking for an explanation of REST.
As you can see from the comments to my answer, we've had a small argument with Darrel Miller on the best media representation of the resources. We've had a further email discussion that resulted in this question.
The main difference between Darrel's and mine understanding of REST is whether the semantic of the data is part of the REST API.
Darrel believes (my interpretation of his words :-)) that the semantic of the data is an essential part of the REST API and as such, the media representation choosen should reflect it. Thus, a proper REST API should choose either:
a well-known media like ATOM to represent the data, so that as many clients could understand the semantic of the resource natively;
an app-specific media type like application/vdn.mycomany.mymedia and expect the client to understand this media type to be able to consume the resources data.
Application/xml is not a good resource representation, as it does not represent the semantic in the media type, yet requires the client to know more about the semantic.
I, on the other hand, believe that the REST API is a separate layer from the actual data representation. The media type exposed by the API is just a container to transfer the resource data. The actual semantic of the data is treated separately. Thus, a client that does not understand the data, can still consume the REST API. Application/xml is a really good data representation, as it allows tight coupling for clients that understand the schema, yet still allows client that don't understand the schema to do some basic processing of the resources.
Thus, the question: is the data semantic part of the REST API? Should we choose only media types for resources representation that actually represent the semantic of the data as well?
I would appreaciate if people post in their answers some citations, preferably from the Roy man himself. :-)
Let's start at the beginning: media types are there to provide the client with a format it can use to decide what to do next. Without an html page, the browser has no links to go to. Without an html renderer, the browser cannot render a page and won't know what to do.
Without a media type, the client has no clue if it will be able to do anything with the byte stream. Indeed, when a client receives the headers specifying application/xml, it has no knowledge of what to do beyond get an xml parser.
So the question really is, should the client be able to make a decision based on the http message without having a look inside the message, or should it go and peek inside the message (or worse, parse the message first) to know what to do.
Lack of media types means that your client will have to do additional peeking work, or worse process the entity body itself, before it can make a decision, be it for rendering or for processing. You now have to add a lot of custom behavior for each of your formats you may want to process, and you loose a bit of coupling in the process.
It's also an http fundamental that intermediaries should be able to process the requests without inspecting the body, and there as well application/xml is problematic.
Now when you say that the semantic of the media types is part or not of the API... What constitutes the API?
From a client perspective, there is no API. There is an initial representation that lets the client make a decision as to what to do next. The media type is indeed where the client gets the information it requires to navigate the "API", and as such there can be no API without representations.
Furthermore, a client should have only three bits of knowledge: a bootstrap location, the HTTP protocol and the media types. The first is only a URI and doesn't convey much beyond the location of a represetnation needed to continue. The second has already very clear semantics. The third is the one where you have control, as it's the contract you have with your client.
That contraact says that whenever you want to do something, the something will have semantics: to add a customer, send a application/vnd.acme.customer+xml to /customers using a POST.
Hence my answer: designing a REST architecture relies on two steps: resource modeling (at the conceptual level) and media type building. Anything else and you're likely doing it wrong.
I don't see the need to be overly pedantic about it. A resource can expose multiple representations; each with its own semantics (and even multiple dimensions of semantics at that). If one representation doesn't provide the semantics required by a particular use case, expose one that does.
Thus, a client that does not
understand the data, can still consume
the REST API.
I'm not sure that's a good litmus test for what does or does not make a decent representation. What good is a client that can consume a document but not understand it well enough to do anything with it? I guess I don't understand how "basic processing of resources" makes application/xml a better choice than some arbitrary blob of 1s and 0s?
Since you asked for references, here's an article from Roy Fielding where he "proposes" a bitmap representation of social network graphs. I can certainly get a machine to display these bitmaps, but of what use is that if I don't understand the underlying social network graph? Would changing the representation to application/xml allow a naive client to extract additional meaning from it that isn't contained in the bitmap? Nope.
Check out this set of slides from Mark Baker for more explanation as to why application/xml does not satisfy the "self-describing" constraint. You can also read a number of posts on his blog including this one where he continues to explain why application/xml + namespace is not equivalent to media-types.
Have you ever seen a good reason to create a custom binary rest protocol instead of using the basic http rest implementation?
I am currently working on a service oriented architecture framework in .Net responsible for hosting and consuming services. I don't want to be based on an existing framework like Remoting or WCF, because I want total flexibility and control for performing custom optimization.
So here I am trying to find the best protocol for handling this SOA framework. I like the request/response stateless connection nature of REST and the uri for defining resources, but I dislike the text based nature of HTTP.
Here are my arguments for disliking HTTP, correct me if I'm wrong:
First an evidence, parsing text is less efficient than parsing binary.
I'd prefer a fixed length binary header containing the content length and a binary content.
Second, there is no notion of sequence number for http requests, so the only way of associating a response with its request is the socket connection used to send the request and receiving the response.
This means there can only be one pending request at a time for a specified socket, so if a service consumer want to send multiple requests in parallel to a service, it need to open multiple socket to the server.
A custom rest protocol could define a sequence number for requests, so request and response would be associated with the sequence number instead of the socket and there could be multiple requests sent in parallel on the same socket.
I think there is no way to do this standardly with HTTP, it could be done with a custom text based protocol, but why not make it binary based to gain performance.
To add a little more context, my SOA framework does not need to be accessible from a non .Net consumer, so I have no restriction about using the .Net binary formatter or another custom binary formatter.
So am I making any sense for wanting a custom binary rest protocol? If you think I'm wrong please tell me your arguments.
Thanks.
REST is an architectural style for constructing web services. Roy Fielding articulated it based on his experience in designing HTTP, but it transcends HTTP. You can deploy a RESTful service over ordinary email exchange for instance.
The REST representations of your resources can be anything you like, though Roy really stresses that people should try to use very carefully designed, standard representations. There's nothing wrong with binary. In fact image representations like JPEG and PNG are binary. Google's Protocol Buffers gives you ways of creating compact binary representations of structured data too.
So the short answer is that you can certainly be RESTful and use binary representations and a home-grown binary substitute for HTTP.
I would actually very strongly recommend you use HTTP for efficiency, though. If you use your own protocol then you lose all the leverage provided by the wonderful HTTP caching infrastructure that stands between your server and its clients. The full client load falls right on your server instead of getting spread out over the intermediate caches.
10/4/2010: In our HTTP-based REST APIs we now support Java Serialized Object and Kryo binary representations in addition to XML, JSON, and XHTML. The Kryo serialization library performs significantly better than the others without requiring any special protocol. Another alternative to cut down on bandwidth is to use HTTP compression along with a textual representation.
The data of your packets can be whatever you like; be it XML, Plaintext, JSON, or just a binary format. I see no reason to force any specific one of these on yourself (use whatever is most fitting).
Though, when saying 'binary format', most people hear a fixed format of field-lengths and other really annoying things. Generally, if you aren't desperate from a data-transfer point of view, I see no reason to go this way [though you may do a binary serialisation of .net objects so they can be re-instantiated [or look at the 'protocol buffers' lib for .net]].
Summary: Seems okay to me. Whatever floats your boat.
Have you ever seen a good reason to create a custom binary rest protocol instead of using the basic http rest implementation?
I'm not sure I understand your terms. A REST representation can be completely binary, and still transported over pure HTTP. There's no need to invent a new protocol just to transmit binary data. Just reduce your requirements to a well-documented media type (which you're free to invent).
Regarding binary resource representations, Fielding himself argues that binary is not only acceptable, but may be required in some situations.
Regardless of whether you go straight binary, Base64 mixed with text, or text-only, don't forget the hypertext constraint if you plan on calling what you do "REST".
So am I making any sense for wanting a custom binary rest protocol?
If you mean you'd like to create a custom, binary-only, hypertext-driven media type - that's perfectly reasonable.
If you're talking about inventing some custom extension to HTTP, I would avoid that unless absolutely necessary (and what you describe doesn't sound to me like it rises to that level).
I want total flexibility and control
Based in this statement then I would suggest one of two choices. Either straight TCP/IP sockets, or WCF. These options give you by far the most flexibility. WCF is a great solution if you want to be transport agnostic and you want to start with a clean state as far as an application protocol is concerned.
REST imposes a set of constraints that restrict how your distributed application behaves in order to gain certain beneficial characteristics. If you see your service end points as ways to invoke operations then I suggest that REST will not fit your needs well at all.
Somehow, I don't think whether you send binary or text payloads should be your biggest concern at this point.