| First off, thanks for taking the time to reply to my admittedly baiting post. I do have a serious point I'm making though. Lets walk through it. http://www.mywebsite.com/api/getAllPageNames/returnType/JSON In this string 'get' appears once. However, as an experienced dev, you know that this is a GET request. To you it looks redundant. However to someone trying to understand what will happen when they hit enter with this URL in their location bar it is meaningful. The question at that point is naturally "But if you don't know that's a GET request then why are you using an API?" This is the point I'm driving at. There are scores of underserved individuals who want to do interesting things with your website that go beyond your GUI, and they are just brave enough to read through your API docs. Now, when I'm thinking about API design I have a big initial choice. Is this API for skilled developers who care about the REST spec? Or is this a tool for as many people as possible to get more out of my service than I have time to accommodate with features. This is where I will always say "I don't care about the spec." A really talented dev will read the docs, discover how my design works, and will write something cool on top of it. I can trust the hackers I know to make things work by hook or by crook. The same cannot be said for someone who really wants to extend my functionality but isn't a talented developer. I feel it's my responsibility to produce a tool that can be used by as many people as possible. I don't want to make a high-end professional camera, I want to make a better point and shoot. I want to extend the abilities of people, not demand they gain a large skillset to use my new tool. New programmers and enthusiastic users are always on my mind. These are the people who's preconceptions are that it should 'just work' and that if it doesn't it's my fault. This is why I applaud decisions like Chrome dropping http://
It simply doesn't matter to 99% of the users of the product, and in fact makes browsers less friendly and more confusing. If I can get my api to work like this, then I will: 'I want to see all the names of pages on mywebsite.com' If I had access to a deterministic natural language parser then I'd use it. As such a thing doesn't yet exist, I try to remain as true to that ideal as possible. The REST architecture may be less confusing than others, but it is far from simple. |
Personally, I'd say that if a developer can't be bothered to read the whole nine(!) verbs of HTTP, he shouldn't use the API. I mean, GET is described in just 11 lines!
And (s)he doesn't need to read your docs: the smart thing about the Uniform Interface described by REST is that the same verbs work on all services of the same architecture (in this case, HTTP). So that knowledge is generic and transferable.
In any case, it's your prerogative to design your API as you wish, but please don't call it REST if you don't intend to follow its principles.