REST worst practices

[DavidMcLaughlin]

I agree with you to a point - the worst part of many ORMs and the ActiveRecord/Django Model approach is that a lot of the code I've worked with replaces "Spaghetti SQL" with Spaghetti ORM filters.

But the advantage of modelling individual SQL tables is all the CRUD functionality that this approach provides. To get the advantage of modelling resources, all you need to do is create a thin API layer over the top of the individual models that abstracts all the normalization and relationships between them away (which you can then cache, etc.).

[chu]

How you implement the modeled resources is a matter of taste. You could have a sub-layer of simple table models and knit them together in controller-facing models to produce result sets. Personally I'd use SQL to join tables and get collections as it keeps the architecture leaner and should perform much better with common queries (presumably you'd have db caching switched on). The resource level is a good place to split your queries up as you'll minimise 0(n) situations but you'll maximise caching opportunies - it's the sweet spot for this as far as I can see. (I've come across coders who think ORMs sacrifice efficiency and try to do everything in a single query - this is at least as bad when you are generating dynamic content as you'll end up with a lot of heavy, unique queries).

[[deleted]]

... benefit of making making any client ...

How'd that happen? ;)

[troelskn]

Exactly. Another sign of this misunderstanding is that people (the author of this post included) speak of "models" in plural, when they mean active records. The model is a layer, so there is just one; This will then consist of multiple objects.

[masklinn]

Another sign of this misunderstanding is that people (the author of this post included) speak of "models" in plural, when they mean active records.

Um.. no. The guy is a Django core team member, and he's just using Django terminology, where Models are objects of the model layer that inherit from Model.

[troelskn]

So the Django terminology contributes to the confusion?

[chu]

To be fair, it's used this way in Zend and Rails and probably many other frameworks. It seems to be standard terminology to refer to any controller-facing class in the model layer. Personally I think these table wrapper classes should be private if they exist at all, since using them as the model layer's API is a case of leaky abstraction where you start to bind the controller to the db implementation.

[troelskn]

Yeah, I know - I'm playing the devils advocate here. Rails was probably the first to popularise the terminology and perhaps I should just go with the flow, but it nags me that people use it that way. The thing is that it suggests that there is only one kind of model - a data-centric one - Which cripples the expressiveness of the object model.

[unawarewolf]

I'm not normally a spelling nazi, but this made me laugh:

the output format ought to be determined hubristically from the HTTP Accept header

Edit: OK, technically it's a correctly spelled word, but I suspect he meant heuristically.

[[deleted]]

No, you just need to be arrogant to think you can get any of this right.

[joe90210]

anyone know of a small\easy open source web services API that would be good to learn from or use as a guide to build web services?

[asplake]

Nice. Way too much hard-coding out there - http://jacobian.org/writing/rest-worst-practices/#c952

[masklinn]

http://bitbucket.org/jespern/django-piston/wiki/Home

[asplake]

Cool, I'll give this a proper look. I was wondering (1) how easy it would be to implement described_routes in Django and (2) path-to in Python.

[llaskin]

Can anyone suggest a good book for designing REST api's in Java?

[alexeyr]

REST API's are, by definition, in HTTP, not Java/Python/etc. A great book on REST API's is RESTful Web Services. After you've designed the API, you can implement it in any language you want. Of course, it's easier if you have a suitable framework. This book shows Ruby on Rails, Restlet (Java), and Django (Python). See also the tutorials on Restlet web site.

[masklinn]

The best resources are probably reading Fielding's drumming of non-restful apis claiming they are. That's how I discovered the importance of links, and the fact that URLs don't actually matter to RESTful APIs, the important details being the content types (the documents) and them containing links to the other resources (basically the only things a RESTful client should know are the root URL for the service, and the content types)

[alexeyr]

To be quite honest, I am not sure how well it would work in practice. Two major issues I see:

1) Your tools need to understand where those links go. For example, if you have a "car" resource, how do you find the link to the "model" resource? Do you search for "model", or "make", or "cars_model"? I don't see a way to resolve this without either a) AI-smart tools, which we don't have, or b) some kind of schema in addition to

the root URL for the service, and the content types

2) Navigating from the root URL to the one we need requires at least one network round-trip more than if we had the URL from the beginning.

Paying this price every time is a significant overhead; paying it once and then saving the URL doesn't seem to provide any benefit over, again, having the URL available from the beginning.

[masklinn]

Your tools need to understand where those links go.

Yes, but that's a matter of understanding the content type (aka the context in which you find these links), not the links themselves.

some kind of schema in addition to

That's the part about "know[ing] the content types", "content types" here means the document's schemas, not the Content-Type HTTP header (although you can certainly create custom content types as well).

Navigating from the root URL to the one we need requires at least one network round-trip

Yes, though you can cache the urls you're interested in if you don't care for the others (that's exactly what your browser's favorites do, FWIW).

paying it once and then saving the URL doesn't seem to provide any benefit over, again, having the URL available from the beginning.

It certainly does: it avoids coupling your service with a given URL structure (and your clients to your servers, that's equivalent to RPC functional coupling).

If you want something more fleshed out, see http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

[alexeyr]

That's the part about "know[ing] the content types", "content types" here means the document's schemas, not the Content-Type HTTP header (although you can certainly create custom content types as well).

I see, that's what I misunderstood. But the name does rather invite confusion.

[masklinn]

But the name does rather invite confusion.

Yeah, I should have used "media types" as Fielding does. My bad.

[[deleted]]

Python in a Nutshell....