Question

I’ve been searching a lot for a clear answer or explanation, but can’t find a thorough one.

I’m building mobile app, which is mostly based on data from my backend.
I can structure most of my requests to my server (php based) using pure restful request or requests with query strings.

2 questions:

1. Let’s say I have a friend class. I want to get or set Dani’s friends.

In rest I would do:

http://www.example.com/Dani/friends - GET (to get all his friends)
http://www.example.com/Dani/friends - POST (to create a new friend for Dani)

Using queried strings:

Http://www.example.com/ user=Dani & action=get_friends (GET method I assume?)
http://www.example.com/ user=Dani & action=add_friend (POST method I assume?)

So, for the first example we have caching in place, plus one constant very readable URL.

In the second, we don’t really have a cache (even if there is, you somehow have to tell your proxy to refresh the cache of the list of friends, after one call the second URL to add friend), since those are 2 different URIs. In rest, it’s done automatically by definition of http methods (post/put makes the resource “dirty”)

Am I right here?

I want to know what’s the best option:
Caching-wise, security, single point of entry (in php code), simper to implement (in both client and server) and so…

2. How would I construct a url to find only a certain friends’ photos? (Let’s say the ones at a certain location.)

I thought of:

http://www.example.com/Dani/friends?long=1&lat=2&field=photos

Is this right, or is there a better way?

Answer 1

URL Construction
One of the most critical things to remember about REST URL construction is that each URL should identify a single resource. In general, this means that URLs are typically broken down into parts:

1. Lists of top-level objects: /users and /photos
2. Top-level object instance: /users/1/Dani and /photos/4356
3. Instance-level lists:
   • /users/1/Dani/friends – Dani’s friends
   • /users/1/Dani/photos – Dani’s photos

Resource Interaction
Interacting with these resources (ie. Creating, Reading, Updating, Deleting) are handled through the “HTTP verbs”, or the “HTTP Methods” that each URL is actually called with. The advantage of this is that each resource (or “thing) you have only needs to know how to do 4 different things, meaning you have a much more simple application.

Your application is also much more structured and compartmentalized, making it easier to test and allows you to update and make changes to it much more easily, since things are more loosely coupled.

Once you don’t have a clear 1-1 connection between a single resource and a single URL, you don’t have RESTful URLs anymore. Once you start putting things like action into the query string, you are essentially doing remote procedure calls (RPC) rather than REST. Everything flowing through a central point couples things together more than they need to be, which makes your architecture rigid, hard to change, and very hard to test.

Searching
The trick is that, for any sort of “list” type resource, you can have that list be the result of some sort of query. There’s nothing that says the list always has to be the same. It wouldn’t make sense to use http://www.example.com/Dani/friends?long=1&lat=2&field=photos because that would return you a list of photos of Dani’s friends, which is getting rather far away from Dani the User.

Since you are looking for Photos, and we already have a URL that identifies a “List of Photos” resource, that is the URL we should be using, but just to get those photos with certain attributes.

So, for your example of finding all of the photos that belong to a certain user (who might be one of Dani’s friends, you might do something like:

GET /photos?owner=[userId]

and you could perhaps look for only photos taken within 1km from some lat/long coordinate:

GET /photos?owner=[userId]&radius=1&lat=[someLat]&long=[someLong]

Or if you are looking a bit more broadly, perhaps you want the photos of all of Dani’s friends from that area:

GET /photos?ownerFriendOf=[Dani's userId]&radius=1&lat=[someLat]&long=[someLong]

In all of these cases, you are searching the list of photos based on the query string you are sending to the photo list, which lives at /photos.

Caching
Caching is only an “added bonus”. In theory, just about any request can be cached, but you don’t need to worry about that right now. In general, however, if you stick to a REST architecture, you will be fine once the times comes.

Security
HTTP has a number of built-in ways of dealing with security, and any of them will work, depending on how secure you need your application to be. Basic and Digest security work well for app-to-app communication since they send their authentication tokens (ie. username and password) along with the request. For a security flow that involves a user, however, you are likely to want to use a Session mechanism and use HTTP Cookie headers to keep track of the session.

In all cases, however, any time a username/password is moving from the client to the server, it should be over a secure SSL (https) connection to keep evildoers from sniffing it. For particularly sensitive applications, all interaction may be through an SSL connection, and for other applications only the login sequence might be. In general, however, being more secure is better than less.

Implementation Simplicity
On the security front, most web frameworks have built-in methods that can handle all of the security methods I just mentioned. You may be wondering if you need to use a web framework, and while it isn’t strictly required, it will dramatically reduce the amount of work you have to do and at the same time it will reduce the number of bugs because most of the “heavy lifting” is handled by the framework and has been very well tested.

Many frameworks today have built-in support for handling RESTful requests and you can quickly get up and running. RPC based support is often less supported, since it doesn’t have as clearly a defined application architecture as REST, but it is still possible with just about any framework.

In the long-run, however, you are likely to get much more bang for your buck by going with a RESTful architecture.