Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

This all may come across very newbish, but I'm trying to wrap my head around designing a website that is thoroughly RESTful. I understand applying RESTful design to things like Users, Photos, Blog Posts, etc. because I think of them like "objects".

But, what about an "about us" page. What kind of resource is that? Is it even a resource in the RESTful sense of the word? Also, say I go to the URL "http://www.example.com/", what resource am I asking for? The index resource?

share|improve this question
    
I think some clarification is needed. What is your end goal. What is the need for restful design. taking restful out of the equation, what need are you trying to satisfy? –  Jonathan Kaufman Apr 12 '11 at 17:14
    
The end goal is a complete website. Structuring a website around restful design seems to make sense based on the way the web works. I'm just not sure how to apply that kind of design to things that don't seem like resources, such as an about or contact page. –  TaylorOtwell Apr 12 '11 at 17:25
add comment

3 Answers

up vote 5 down vote accepted

The most common RESTful web site resource pattern I see is to add a view to the URI:

/ resourcetype / identifier [/ view] [/ page] [?filterparams]

When there is no view, you simply serve a default view. In your case:

  • / — a request for example.com returns the default view for the top-level resource - your website.
  • /aboutus — the "About us" view of the top-level resource. Or, alternatively, aboutus could be a named identifier for a resource in the scope of the top-level CMS.*
  • /customers/1/aboutus — this request would indicate an "About us" view scoped to customer 1.

That being said, sometimes it's best to fudge a little for better semantics. For example, StackOverflow uses the RESTful /questions/[id] for questions, but the Ask Question page is /questions/ask which isn't very RESTful (ask is not a questions resource) but makes a lot of sense to use mere mortals.


* In CMS's at the top level, the resource type is often, but not always, removed because it is redundant.

share|improve this answer
add comment

Keep in mind that RESTful design per se is intended to provide a standard by which the web becomes uniformly programmable. It is not always appropriate or useful to shoe-horn your entire human-facing website into pure REST semantics.

When you have resources, considering their representations is useful. It is also important to consider the other design principles of REST, such as statelessnes, and how they impact the performance and usability of your website. But remember that REST is a tool, not a goal. It's a means, not an end.

Use RESTful semantics where useful, after understanding their purpose and benefits, and don't sweat it if your site isn't perfectly RESTful. It would be almost impossible for any non-trivial site in any event.

TL;DR: REST is a tool. Use it when and where it is useful but don't be bound by it.

share|improve this answer
    
+1 There's more to rest than URLS. –  Josh Noe Jul 12 '13 at 14:39
add comment

But, what about an "about us" page[?] What kind of resource is that?

Complex. Nothing wrong with a resource that has components, pieces or structure.

Resources aren't "relational database rows" or other atomic things. They're resources.

Document-oriented databases handle this more gracefully because a resource can be larger and more structured.

Is it even a resource in the RESTful sense of the word?

Yes.

Also, say I go to the URL "http://www.example.com/", what resource am I asking for?

No.

You're asking for the "aboutus" resource. It's possible (but odd) for a resource to be a singleton. No ID and not a "list".

http://www.example.com/aboutus/?format=xml

Returns a complex XML document with lots of pieces and parts. Nothing wrong with that.

The index resource?

Doesn't mean much in a "RESTful" sense. The "index" page is for people. An application that uses a RESTful API is designed to request specific kinds of resources.

share|improve this answer
4  
+1 I'd like to tease an important point out of your answer: REST is a programmable paradigm; it is not necessarily intended for human consumption. –  Rein Henrichs Apr 12 '11 at 17:49
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.