UPDATE: please read my followup
So I’ve been in the process of converting beeets.com, which is currently a “website” with integrated back-end code, to a front-end with a back-end API. It’s been an interesting journey, and has spawned a lot of thought recently about how to implement the API.
Obviously, whenever someone says web API, REST is the first this that comes to mind. “Let’s make it a REST API!” From what I’ve been reading about REST (I tend not to use terminology without knowing what the hell it means) many “REST” services aren’t very RESTful (“How I Explained REST to My Wife” – great intro to REST). In fact, the way I’ve implemented the beeets API happens to be closer to RPC. After doing my fair share of research, I’m ok with this.
REST seems like an excellent architecture. In fact, one of the world’s largest global networks is built on that architecture. It works well for what it does…but what the hell does it do? From what I’ve been reading, it gives “resources” (pieces of information) a single location to be accessed/updated/created/deleted. At least this is how it works on the web.
RPC is basically a function or method that runs on a remote machine that can be called by a local machine, completely transparent to the local code. Most RPC implementations work on their own conventions, separately from the beautiful architecture which is REST…what is otherwise known as reinventing the wheel.
So why am I okay with using RPC in the beeets API? The main reason is that RESTful authentication is total junk. It’s great for server-server communication, but NOT so great for user interactions. Users are used to seeing pretty login boxes with “forgot your password? reset it, moron!” or “create an account!” links. Popping up an HTTP login screen is not cool. It’s not cool. This is my main problem with REST.
That being said, if you cannot authenticate REST, then using the built-in methods POST, PUT, DELETE are more or less worthless, unless you have a completely public set of information that anybody can add to, change, or remove…in which case, REST would kick ass.
In light of REST lacking in this area, I think the following makes sense. Create an RPC API that authenticated servers can call to get/create/update/delete information. IPhones, Facebook apps, etc can use this RPC for interacting with the actual dataset. Then on the www front-end, create a REST system that only implements GET.
So I could go to beeets.com/events/123-native-american-slaughter-celebration and get an HTML page with links I can click, an awesome layout, etc. I could go to beeets.com/events/123-native-american-slaughter-celebration.json and get a JSON representation of that event, with URLs to other pages which could be JSON-encoded if need be.
In other words, create a read-only RESTful service on top of the www site, and use an RPC for create/update/delete interactions with the dataset. The already-public information is freely accessibly, without any sort of authentication, so any person or system that cares to consume it can do so. This way you’re still mapping a resource to a location, and providing multiple consumption formats for said resource.
If there is any other way to authenticate users against a RESTful system without an HTTP login, and while being able to control the actual login/registration flow and layout, PLEASE let me know!