[iandanforth]

This is an excellent example of a spec being deemed more important than a useable system.

Frankly, I don't give a damn about the REST spec, and neither should you. When I see an API I want it to be simple and clear.

/getAllPages/

Hey, it's a verb and I've got a pretty good idea of what I'm going to get back

/getAllPageNames/returnType/JSON

Now I really know what I'm getting. The simplicity and usability of this structure absolutely trumps a spec compliant call that involves request headers and nouns.

If you're building a system that requires having read someones dissertation, you're not doing us any favors. Especially when it comes to an API. Keep it simple, stupid.

Remember that your understanding of what a URL 'is' or 'should be' comes from a great deal of technical experience. If you're not working day in and day out to make powerful tools accessible to people WITHOUT such experience, please stop programming. Really, get out of the pool. Whatever awesome knowledge you need to make a system work internally is invaluable, but your interfaces should make the world a simpler, more magical place.

[binarymax]

Did you read the article? No matter nouns or verbs but in your example you are doing an HTTP GET. Does get getallpages sound right to you?

I did not downvote you but the REST architecture is well thought out, simple to follow, and very sufficient if you are moving content over HTTP.

[iandanforth]

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.

[icebraining]

But you still have to make a GET request and hence understand what that verb does - so you don't really gain anything - and now you're creating ambiguities for the API users. What if I POST to 'getAllPageNames'? It doesn't make sense, does it?

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.

[thedebuggr]

I agree! Making such api make it really confusing. And what if one have to support other verbs. Then, One will end creating apis for each verb. A programmer who is using this APIs knows about HTTP and he knows about verb..making it explicit in the url will make confusing for most developers.

[balakk]

> 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?"

Your efforts to build what you perceive as the more accessible API is appreciated. However please take the time to understand the alternate viewpoint, it might be useful sometime.

The whole point of REST is I mostly do not have to study another API documentation. The "uniform interface" is not a limitation, it is a feature.

I suspect you may be underestimating your user-base. If your website has useful enough content, somebody is bound to write a programmable interface, RESTful or not.

[pbreit]

GET /pages.json?