> > Instead of versioning urls, we can use the Accept header to specify > the version of the API the client needs. > Even more blank faces.
The last time I was involved in building an external-facing API, using the Accept header for versioning was considered, but rejected. We adopted a different principle: make it easy to use the API in a browser*. Fiddling with Accept headers in the browser is a pain. In that particular case, we also adhered to HATEOAS with a single root URL and the resultant links in each resource. I'm still undecided whether it is always clear cut that it's a Good Thing. It's more effort to implement the API, and it's more effort and uses more resources to consume the API**. Seems the benefits are about providing stability for clients while evolving on the server. If you have control over the client and server, you can manage evolving both in lockstep. If you're exposing an API to external parties, you may value having the freedom to evolve the API without disrupting clients. I find it analogous to any API you provide: sometimes you lock things down and don't guarantee anything to provide yourself the freedom to change, sometimes you expose more to give convenience for the client, then have to live within that constraint. Like most choices we make: it depends :-) * we found it enabled better collaboration with our product managers, easier testing & verification, etc. ** to retrieve a resource deep in the tree, you have to traverse from the route, with a round trip for each link that you follow On 31 January 2014 16:53, Chris Phelps <[email protected]> wrote: > In the APIs I've worked on, I have seen good use of linking to related > objects by URI, but not too much further use of HATEOAS. We were starting > to experiment with including or excluding links to indicate permissions to > a feature (if a user did not have the appropriate role he would not get > that link in the response), but this didn't really go beyond talking it out. > > We did not version our API via the accept headers. This seems like an > approach that would work well if you are versioning the data you are > returning, or if you are really all the way there with HATEOAS, but if you > aren't doing so I would think using the accept header for versioning would > complicate the code that's building the URIs. > > I think going to HATEOAS is a technique that will help you achieve > flexibility in your API, but like many approaches to flexibility, you pay a > cost. Whether this cost is worth it or not is a good tradeoff in your > design, though it's quite possible that by the time you really need the > flexibility it is difficult to add in. Also, as you note, not all > developers have really thought through or worked through how these > techniques would work, so there's a cost involved to get people comfortable > to really evaluate the tradeoffs as well. > > For sure, if your current API is not consistently and properly using HTTP > verbs, that's the biggest place to focus your efforts. If your team is not > used to that approach, even that step may take some time to get everyone to > a place where it is intuitive and more natural than the previous approaches. > > -C > > > On Fri, Jan 31, 2014 at 2:58 AM, Rakesh <[email protected]>wrote: > >> Hi, >> >> ok be honest, how many of you actually do it all the way? >> >> So many times I hear teams saying they have designed a RESTful >> interface but when you dig further you find: >> >> 1. Only GET and POST requests >> 2. versioning in the urls >> 3. Clients store all the urls for the service in configuration locally. >> >> Is doing it 'by the book' just a fallacy and to difficult in practice? >> >> I've just tried explaining the notion of having the client only know >> the root url of the service and be given valid paths for where to go >> next so the clients don't store all the urls. >> >> Blank faces. >> >> Instead of versioning urls, we can use the Accept header to specify >> the version of the API the client needs. >> >> Even more blank faces. >> >> We currently have a very poor API and have the opportunity to do it >> again properly. Should I fight to do it properly? Or be content with >> just getting GET/POST/PUT/DELETE used correctly? >> >> The idea of telling the client where to go next is very powerful to me >> (its basically a state machine right?) but its complicated to >> implement and new territory for the devs (me included). >> >> I'm also loathe to do it with a framework but if its to hard to do >> manually, I'll probably drop it to. >> >> Any insights? >> >> Cheers >> >> Rakesh >> >> -- >> You received this message because you are subscribed to the Google Groups >> "Java Posse" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to [email protected]. >> To post to this group, send email to [email protected]. >> Visit this group at http://groups.google.com/group/javaposse. >> For more options, visit https://groups.google.com/groups/opt_out. >> > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/javaposse. > For more options, visit https://groups.google.com/groups/opt_out. > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/javaposse. For more options, visit https://groups.google.com/groups/opt_out.
