I am currently learning REST practices with the help of the excellent book of Richardson "RESTful Web Services". I would like to design a REST API that follows the maturity model of Richardson, especially the level 3 called HATEOAS which seems to be the most complicate to handle.
Firstly, I don't really understand the different meaning between a link and a form ?(regarding the hypermedia, I know the HTML explanation..).
Is it simply a matter of "link is for GET method" and "form is for GET/POST/PUT methods" ?
EDIT1: I got the point: forms can be application forms for constructing a URI and use a GET method or can be resource forms for PUT/POST methods (more or less what i asked). Correct me if I'm wrong, links are supposed to be use carefully by the client with the OPTIONS method to know how it can be use.
As I want to be compliant to HATEOAS, I need to choose an hypermedia format... and I know that it exists several of format such as Siren, HAL, Collection+JSON, JSON-LD, Hydra, etc...
But well, I don't know which one to use ?
In the Richardson's book, he uses xHTML which has one main good point: testing your API with a browser. But xHTML seems to be heavy.
I would probably prefer something more lightweight but the recent hypermedia format (Siren, HAL, ...) are probably too recent and complex to test without a programmable client.
I would definitely recommend you to give it a try to the siren format for your API. As they correctly mentioned in one of the comments in has a nice browser...but that one is poorly supported (you can see it in their github repository).
So you should use this one which was based on the first mentioned but it has some extras like: nice error handling & supports actions for nested entities (among others)
Regarding the difference between link and forms... well my 5 cents are that you use links for GET requests that require no input params from your client and actions (talking in siren format) for POST, PUT, PATCH, GET actions that do require sending some params to the server.
Now, you could say: "But I can have this link http://testsite.com/api/v1/users?param1=value1" and still be passing params. You're correct, BUT!, how would your client now that it can pass this or that param.
That's why you have actions with a key called 'fields' where you describe the fields you're willing to accept.
Enjoy hypermedia APIs!
Related
I've never really heard of HAL until I started working on a new project that is making use of it. From what I can tell, it's basically a way to easily follow links to traverse your way around a restful API's structure.
So if I understand this correctly, both tools are to make it easier to traverse around an API's documentation to see all the different means of communicating with said API. Essentially both of these are tools used for documentation purposes only?
REST APIs must be hypertext driven. It's not merely for documentation purposes, but for driving all interaction with the API. If you're not driving the interaction through links and clients are building URIs from templates in documentation, it's not RESTful. The authors of Django-REST-Framework themselves recognize the name is inadequate.
http://www.django-rest-framework.org/topics/rest-hypermedia-hateoas/
You should read the links provided in that document, specially this one:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
With that in mind, your REST API has to use a data format where links are standardized so clients know how to parse them. This would constrain most APIs to use HTML or XML, but since JSON is such a popular data-exchange format, there are some efforts into designing conventions for adding hypermedia-awareness to any format, like HAL.
Django-REST-Framework supports hyperlinks in the HTML output, but -- AFAIK -- it has no support for hyperlinks in other formats. You can use HAL-JSON if you want, but you'll have to implement support for it.
I would like to use ember-data in a project I am building, but the API I am working with does not follow REST conventions.
For example, all the HTTP requests are POST and the naming conventions of the endpoints are unique to the actions they perform. e.g. /api/thing/retrieve would require me to post a JSON object with some parameters, and would return a 'thing' to me.
Do I use the Restful adapter and reopen the class and redefine the various find functions?
OR
Do I have to make a new adapter?
OR
Should I just abandon ember-data and and use ajax in my models(or maybe even controllers)?
I'm not sure how I would handle any of those options. Any guidance would be appreciated.
The only information which I have seen on this subject has been an article by the Discourse folks linked below.
http://eviltrout.com/2013/03/23/ember-without-data.html
I personally have toyed around with the reopenClass method in the article, and would probably drop it into a mixin or something to that effect if I had a consistent but non-REST API which I was calling regularly.
I would say that, if your API is consistent (reliable) then you should create/extend the DS.Adapter (not DS.RESTAdapter) to implement to your specification.
All the hooks are there, you will just end up defining it once which all models can use.
I would also read through the Basic Adapter code - (https://github.com/emberjs/data/blob/master/packages/ember-data/lib/adapters/basic_adapter.js) it might be a better staring point for you then DS.Adapter.
If your API is not reliable, then you are probably better off with just using the $.ajax() calls as necessary. But, in my opinion, that does not scale well.
A link worth reading when looking at Basic Adapter: http://emberjs.com/blog/2013/03/22/stabilizing-ember-data.html
One last note, building an ORM or even a something more simple then an ORM is not a trivial task, that for me, makes using ember-data worth the effort, and yes sometimes pain.
I am writing a C++ API which is to be used as a web service. The functions in the API take in images/path_to_images as input parameters, process them, and give a different set of images/paths_to_images as outputs. I was thinking of implementing a REST interface to enable developers to use this API for their projects (independent of whatever language they'd like to work in). But, I understand REST is good only when you have a collection of data that you want to query or manipulate, which is not exactly the case here.
[The collection I have is of different functions that manipulate the supplied data.]
So, is it better for me to implement an RPC interface for this, or can this be done using REST itself?
Like lcfseth, I would also go for REST. REST is indeed resource-based and, in your case, you might consider that there's no resource to deal with. However, that's not exactly true, the image converter in your system is the resource. You POST images to it and it returns new images. So I'd simply create a URL such as:
POST http://example.com/image-converter
You POST images to it and it returns some array with the path to the new images.
Potentially, you could also have:
GET http://example.com/image-converter
which could tell you about the status of the image conversion (assuming it is a time consuming process).
The advantage of doing it like that is that you are re-using HTTP verbs that developers are familiar with, the interface is almost self-documenting (though of course you still need to document the format accepted and returned by the POST call). With RPC, you would have to define new verbs and document them.
REST use common operation GET,POST,DELETE,HEAD,PUT. As you can imagine, this is very data oriented. However there is no restriction on the data type and no restriction on the size of the data (none I'm aware of anyway).
So it's possible to use it in almost every context (including sending binary data). One of the advantages of REST is that web browser understand REST and your user won't need to have a dedicated application to send requests.
RPC presents more possibilities and can also be used. You can define custom operations for example.
Not sure you need that much power given what you intend to do.
Personally I would go with REST.
Here's a link you might wanna read:
http://www.sitepen.com/blog/2008/03/25/rest-and-rpc-relationship/
Compared to RPC, REST's(json style interface) is lightweight, it's easy for API user to use. RPC(soap/xml) seems complex and heavy.
I guess that what you want is HTTP+JSON based API, not the REST API that claimed by the REST author
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
I've been struggling with understanding a few points I keep reading regarding RESTful services. I'm hoping someone can help clarify.
1a) There seems to be a general aversion to generated code when talking about RESTful services.
1b) The argument that if you use a WADL to generate a client for a RESTful service, when the service changes - so does your client code.
Why I don't get it: Whether you are referencing a WADL and using generated code or you have manually extracted data from a RESTful response and mapped them to your UI (or whatever you're doing with them) if something changes in the underlying service it seems just as likely that the code will break in both cases. For instance, if the data returned changes from FirstName and LastName to FullName, in both instances you will have to update your code to grab the new field and perhaps handle it differently.
2) The argument that RESTful services don't need a WADL because the return types should be well-known MIME types and you should already know how to handle them.
Why I don't get it: Is the expectation that for every "type" of data a service returns there will be a unique MIME type in existence? If this is the case, does that mean the consumer of the RESTful services is expected to read the RFC to determine the structure of the returned data, how to use each field, etc.?
I've done a lot of reading to try to figure this out for myself so I hope someone can provide concrete examples and real-world scenarios.
REST can be very subtle. I've also done lots of reading on it and every once in a while I went back and read Chapter 5 of Fielding's dissertation, each time finding more insight. It was as clear as mud the first time (all though some things made sense) but only got better once I tried to apply the principles and used the building blocks.
So, based on my current understanding let's give it a go:
Why do RESTafarians not like code generation?
The short answer: If you make use of hypermedia (+links) There is no need.
Context: Explicitly defining a contract (WADL) between client and server does not reduce coupling enough: If you change the server the client breaks and you need to regenerate the code. (IMHO even automating it is just a patch to the underlying coupling issue).
REST helps you to decouple on different levels. Hypermedia discoverability is one of the goods ones to start with. See also the related concept HATEOAS
We let the client “discover” what can be done from the resource we are operating on instead of defining a contract before. We load the resource, check for “named links” and then follow those links or fill in forms (or links to forms) to update the resource. The server acts as a guide to the client via the options it proposes based on state. (Think business process / workflow / behavior). If we use a contract we need to know this "out of band" information and update the contract on change.
If we use hypermedia with links there is no need to have “separate contract”. Everything is included within the hypermedia – why design a separate document? Even URI templates are out of band information but if kept simple can work like Amazon S3.
Yes, we still need a common ground to stand on when transferring representations (hypermedia), so we define your own media types or use widely accepted ones such as Atom or Micro-formats. Thus, with the constraints of basic building blocks (link + forms + data - hypermedia) we reduce coupling by keeping out of band information to a minimum.
As first it seems that going for hypermedia does not change the impact of change :) : But, there are subtle differences. For one, if I have a WADL I need to update another doc and deploy/distribute. Using pure hypermedia there is no impact since it's embedded. (Imagine changes rippling through a complex interweave of systems). As per your example having FirstName + LastName and adding FullName does not really impact the clients, but removing First+Last and replacing with FullName does even in hypermedia.
As a side note: The REST uniform interface (verb constraints - GET, PUT, POST, DELETE + other verbs) decouples implementation from services.
Maybe I'm totally wrong but another possibility might be a “psychological kick back” to code generation: WADL makes one think of the WSDL(contract) part in “traditional web services (WSDL+SOAP)” / RPC which goes against REST. In REST state is transferred via hypermedia and not RPC which are method calls to update state on the server.
Disclaimer: I've not completed the referenced article in detail but I does give some great points.
I have worked on API projects for quite a while.
To answer your first question.
Yes, If the services return values change (Ex: First name and Last name becomes Full Name) your code might break. You will no longer get the first name and last name.
You have to understand that WADL is a Agreement. If it has to change, then the client needs to be notified. To avoid breaking the client code, we release a new version of the API.
The version 1.0 will have First Name and last name without breaking your code. We will release 1.1 version which will have the change to Full name.
So the answer in short, WADL is there to stay. As long as you use that version of the API. Your code will not break. If you want to get full name, then you have to move to the new versions. With lot of code generation plugins in the technology market, generating the code should not be a issue.
To answer your next question of why not WADL and how you get to know the mime types.
WADL is for code generation and serves as a contract. With that you can use JAXB or any mapping framework to convert the JSON string to generated bean objects.
If not WADL, you don't need to inspect every element to determine the type. You can easily do this.
var obj =
jQuery.parseJSON('{"name":"John"}');
alert( obj.name === "John" );
Let me know, If you have any questions.
I've been reading up on REST, and I'm trying to figure out what the advantages to using it are. Specifically, what is the advantage to REST-style URLs that make them worth implementing over a more typical GET request with a query string?
Why is this URL:
http://www.parts-depot.com/parts/getPart?id=00345
Considered inferior to this?
http://www.parts-depot.com/parts/00345
In the above examples (taken from here) the second URL is indeed more elegant looking and concise. But it comes at a cost... the first URL is pretty easy to implement in any web language, out of the box. The second requires additional code and/or server configuration to parse out values, as well as additional documentation and time spent explaining the system to junior programmers and justifying it to peers.
So, my question is, aside from the pleasure of having URLs that look cool, what advantages do RESTful URLs gain for me that would make using them worth the cost of implementation?
The hope is that if you make your URL refer to a noun then there is a better chance that you will implement the HTTP verbs correctly. Beyond that there is absolutely no advantage of one URL versus another.
The reality is that the contents of an URL are completely irrelevant to a RESTful system. It is simply an identifier.
It's not what it looks like, it is what you do with it that is important.
One way of looking at REST:
http://tomayko.com/writings/rest-to-my-wife (which has now been taken down, sadly, but can still be see on web.archive.org)
So anyway, HTTP—this protocol Fielding
and his friends created—is all about
applying verbs to nouns. For instance,
when you go to a web page, the browser
does an HTTP GET on the URL you type
in and back comes a web page.
...
Instead, the large majority are busy
writing layers of complex
specifications for doing this stuff in
a different way that isn’t nearly as
useful or eloquent. Nouns aren’t
universal and verbs aren’t
polymorphic. We’re throwing out
decades of real field usage and proven
technique and starting over with
something that looks a lot like other
systems that have failed in the past.
We’re using HTTP but only because it
helps us talk to our network and
security people less. We’re trading
simplicity for flashy tools and
wizards.
One thing that jumps out at me (nice question by the way) is what they describe. The first describes an operation (getPart), the second describes a resource (part 00345).
Also, maybe you couldn't use other HTTP verbs with the first - you'd need a new method for putPart, for example. The second can be reused with different verbs (like PUT, DELETE, POST) to 'manipulate' the resource? I suppose you're also kinda saying GET twice - once with the verb, again in the method, so the second is more consistent with the intent of the HTTP protocol?
One that I always like as a savvy web-user, but certainly shouldn't be used as a guiding principle for when to use such a URL scheme is that those types of URLs are "hackable". In particular for things like blogs where I can just edit a date or a page number within a URL instead of having to find where the "next page" button is.
The biggest advantage of REST IMO is that it allows a clean way to use the HTTP Verbs (which are the most important on REST services). Actually, using REST means you are using the HTTP protocol and its verbs.
Using your urls, and imagining you want to post a "part", instead of getting it
First case should be like this:
You are using a GET where you should have used a post
http://www.parts-depot.com/parts/postPart?param1=lalala¶m2=lelele¶m3=lilili
While on a REST context, it should be
http://www.parts-depot.com/parts
and on the body, (for example) a xml like this
<part>
<param1>lalala<param1>
<param2>lelele<param1>
<param3>lilili<param1>
</part>
URI semantics are defined by RFC 2396. The extracts particularly pertinent to this question are 3.3. "Path Component":
The path component contains data, specific to the authority (or the
scheme if there is no authority component), identifying the resource
within the scope of that scheme and authority.
And 3.4 "Query Component":
The query component is a string of information to be interpreted by
the resource.
Note that the query component is not part of the resource identifier, it is merely information to be interpreted by the resource.
As such, the resource being identified by your first example is actually just /parts/getPart. If your intention is that the URL should identify one specific part resource then the first example does not do that, whereas the second one (/parts/00345) does.
So the 'advantage' of the second style of URL is that it is semantically correct, whereas the first one is not.
"The second requires additional code
and/or server configuration to parse
out values,"
Really? You choose a poor framework, then. My experience is that the RESTful version is exactly the same amount of code. Maybe I just lucked into a cool framework.
"as well as additional documentation
and time spent explaining the system
to junior programmers"
Only once. After they get it, you shouldn't have to explain it again.
"and justifying it to peers."
Only once. After they get it, you shouldn't have to explain it again.
Don't use query/search parts in URLs which aren't queries or searches, if you do that - according to the URL spec - you are likely implying something about that resource that you don't really want to.
Use query parts for resources that are a subset of some bigger resource - pagination is a good example of where this could be applied.