REST, API - confusion

[eluser]tinawina[/eluser]
Before I get too far into my project..., I have a couple of questions about the best way to go about architecting our site. I've written about my project in this forum before. In a nutshell, we are putting together a site that archives research works (reports, data sets, etc.) and let's people login and post comments about works, tag them, save them to their own personal research library, etc.

In the end we want to make sure that our resources are easy to access and share not only through our site, RSS feeds and e-newsletters, but also through mashups that others might want to do.

I've been reading about REST and I find it confusing. Some people say use nouns to describe resources and move people through your site:

www.oursite.org/research/listing/the-name-of-a-report

Others say verbs are required:

www.oursite.org/research/getListing/the-name-of-a-report

I must confess, I have no idea why one way would be better than the other. Throw in API and mashup and I get really lost. Does anyone have a way to think about this or a process to use to figure out the best way forward? Especially given that I'm def using CI/OOP/MVC? Thanks for any insight!

[eluser]Jay Callicott[/eluser]
We are paying a guy who's doing an image API with rest and initially it was confusing to me. As far as verbs or no verbs probably whatever makes the most sense for you is what I'd go with.

I think REST has low overhead in the way of markup for making requests also it's confusing configuring custom headers if you haven't done that before. Custom headers are simply key/value pairs so it's nice to be able to receive key value pairs in the headers instead of plain text or XML markup but obviously if you need more markup you're going to need XML.

I've alternatively used php 5 web services which are OK but have a lot of markup. The interoperability with other platforms is a concern where REST is 100% platform independent to my knowledge.

I've also used just URI/POST calls for small web services where I was just spitting out HTML and that worked pretty well for me. I didn't need key value pairs and figuring out how to POST data to a URL is easier than figuring out custom headers and whatnot. That method though wouldn't return key/value pairs, just straight HTML or it could have been XML.

My thought is that the whole URI schema of REST is a nice principle and the GET/DELETE/POST commands seem to make sense so long as you know how to customize curl calls.

For simpler needs just handling POST or GET requests and spitting out plain text or XML seems to be easier to implement and more straight forward to me.

[eluser]tinawina[/eluser]
Ok - I was in over my head before. Now I'm WAY in over my head.

Thanks Jay - you give me some keywords to use in my next google excursion.

What you say seems right re: choosing to use nouns over verbs or vice versa. It seems to me we have some easily noun-able resources -- www..../research, www..../comments, www...../members, www..../member/profile/screen_name. I run into trouble when I try to think about things like searching or browsing. In that case, do we go with /research/search or is /search/research the better way to go. Is this truly just personal preference? Or is there a reason to use one over the other?

Also - am I correct in thinking about our site as two different streams of outgoing resources? One stream: people visiting the site and more than likely interacting with our "noun-ables". The other stream: other systems requesting resources from our site and so probably needing our "verbs", eg., getResearch (to use in our application somewhere else)? Are we architecting out two separate things -- a website and an API? Does that even make sense? Do you get a sense as to how much I'm overthinking this??

Thanks again!

[EDIT] Here's a link to a blog post on REST that was written in 2005 and sustained comments through 8/2007. Some good links, insights. http://www.sitepoint.com/blogs/2005/11/2...gets-rest/

[eluser]Jay Callicott[/eluser]
Hey there, I think you are overthinking it. I would go with whatever makes sense to you. Having well written nouns/verbs for URLs are helpful but most users never look at the URL because they are just clicking on links and buttons. Some like putting gets in front of everything, I don't like those as much myself.

I have problems all the time trying to decide what to name my controllers and methods. In Code Igniter you can remap URLs and that is helpful sometimes but it's still tricky to make the URL readable. I agree with that.

I looked at that article you posted and it's interesting though I've never thought of removing verbs. I usually have for every table add/edit/delete/index and sometimes search. So for users I'd have users/add, users/delete, etc. I think it makes sense to me. I don't know how I'd express it as clearly without those verbs.

I would say the first word, which is the controller name in CI shouldn't be a verb. Sometimes I've named my controller search bc I only have 1 item of content to search but then later I want a search page for something else that should really be in it's own controller so I would say that makes more sense than removing verbs altogether.

Hope that's helpful.

[eluser]tinawina[/eluser]
Yes - I see your points. And yes I am overthinking it. I tend to do that, it's a fatal flaw -- or my charm, take your pick.

I've been thinking (uh oh) about this more, and trying to apply K.I.S.S. to this effort. I think these URLs would work fine for us where users are concerned:

www.oursite.org/users/screen_name (displays this user's profile info)
www.oursite.org/users/allUsers (displays a list of all active users)
www.oursite.org/users/screen_name/updatePassword (user can get to update screens when logged in)
www.oursite.org/users/screen_name/updateProfile
www.oursite.org/users/screen_name/updateEmail

We also have research contributors who need to create a different kind of account (tied up with copyright on research). Much of what they need to do overlaps with processes used in the User account creation and maintenance routines. Can I ask -- is handling all of my User stuff in one controller the right way to go? Or should I expand User to include Contributors too since they share processes with the difference being only in table names and a few field names?

Say I have a controller called Users with these methods:

- createUser (wh would include validation and callbacks for unique data)
- updateProfile
- updatePassword (same here with validation and callbacks)
- updateEmail (and here...)
- deleteUser (admins only)
- displayUser
- displayAllUsers

I'm thinking this is the way to go since I'd only have to deal with password and email callback code needed in the createUser, updatePassword and updateEmail methods once in this one controller. And this puts my user stuff in one place (with required model and view calls).

Unfortunately I have a need for the password callback when I let a user reset their password via the password-finder tool. I'm really trying to avoid duplicate code! But all things related to login are in my Login controller in an attempt to be organized.

I could also use the callback code for email and password check (as well as username check) for research contributors. But my research contributors do a lot of other things that Users don't -- like add and maintain research listings.

How would you handle this? Would you sacrifice duplicate code for clear controller organization?

[eluser]Jay Callicott[/eluser]
I usually will try to remove duplication in that case. You don't want to have 2 different controllers with the same methods for adding users, showing an index, viewing the details, etc.

I use some form of the factory pattern for instances where I want to have for instance users with more methods.

There are different ways of doing this. You could have a base model and have each child model inherit methods overriding and extending where necessary, you could use delegate functions instead of inheritance.

The annoying thing about models is that you can't pass initialization parameters like you can with libraries. So sometimes I create an initialize function. Something like $this->load->model('User_model'), then User_model->intialize(array(params..)); and then call your functions and when you call User_model->find it will call whichever child model you've initialized. That way you can have a consistent interface.

I also always use a user access class for determining access to a controller function and i call an authorization check before i do anything in that function. When users log in I store all of their stuff in a session var called "user" and refer to that when im determining what kind of user they are.

You could also use that session var to initialize your model.

In the constructor you could look at the user session variable and maybe you have a property that indicates what type of user they are. In your parent class that's how you know which child model to initialize.

The important thing with that is that you should try to limit how many times you check what type of user it is.

You don't want switch statements all over the place.

Anyways that's one of the simpler design patterns I use, I don't know a lot of design patterns but that one is one I employ alot. Clear as mud?

[eluser]tinawina[/eluser]
Unbelievably, I sorta get what you are saying! I'm new to OOP and MVC so it's a lot to comprehend, but really - I do catch your drift.

I think it's just hard to figure out where to break things (objects?) apart and build things up. My first attempt at putting together this class quickly became a big procedural glob of code wrapped in the class{} tag. Ahem, not the point. I'm trying this again with the thought that Users is the class and contributors and end-users are sub-classes. I think that will get me closer to where I want to be.

Thanks so much for posting though. You've been really helpful. Appreciate it!

[eluser]Jay Callicott[/eluser]
No problem. I don't try to overcomplicate things myself, I really only use design patterns when I know it will save me a lot of duplication and I really only understand a few. I've read books on design patterns but I think most of them are over my head but get to know that factory design pattern, it will serve you well.