Favorite REST-ful APIs?

[maciej]

Hi everyone,

I'm working on a draft spec for version 2 of the Pinboard API, and one
thing I'd like to hear is which APIs developers on this list have
found an absolute pleasure to use. I want to make sure I steal the
best ideas.

Please do not send me links to any kind of 'best practices' rant about
RESTful API design. Rather, I'd like specific examples of existing
APIs. If you can take some time to explain what about them makes you
happy, all the better.

I'll solicit suggestions for actual API calls in a later message. For
now I'm interested in basic things like URL design, formatting return
data, where verbs 'live' in the API call, and so on.

[Mike Schinkel]

On Feb 7, 2012, at 5:54 PM, maciej wrote:

I'm working on a draft spec for version 2 of the Pinboard API, and one
thing I'd like to hear is which APIs developers on this list have
found an absolute pleasure to use.   I want to make sure I steal the
best ideas.

Please do not send me links to any kind of 'best practices' rant about
RESTful API design.  Rather, I'd like specific examples of existing
APIs.  If you can take some time to explain what about them makes you
happy, all the better.

There is not a single API that I really like, so I hope you won't mind me using one that I like but don't love as an example:

https://www.hipchat.com/docs/api/method/rooms/history

Pros:

- Authentication is simple

- Formats are json or xml

Cons:

- Use of URL parameters for things that would go nicely in URL, i.e. room_id, date and format.

So for the con here's an example URL:

https://api.hipchat.com/v1/rooms/history?format=json&room_id=12345&auth_token=asdefasdefasdefasdef&date=2012-02-01

It would be so much nicer as:

https://api.hipchat.com/v1/rooms/history/12345/2012-02-01.json?auth_token=asdefasdefasdefasdef

The URL format I just proposed makes it much easier to use the API in one's browser to test the API across room IDs, dates and formats. Even better, make sure that the API can easily be accessed via the browser URL to enable super easy testing.

Lastly, if you had to choose only one data format use application/x-www-form-urlencoded for HTTP POST and GET request and json for HTTP POST and GET response.

-Mike

[Mike Schinkel]

I sent that last email too soon.

Another Pro:

- When they used nouns in URLs well.

Other Cons:

- When they use verbs in URLs:

https://www.hipchat.com/docs/api/method/rooms/create

https://www.hipchat.com/docs/api/method/rooms/delete

https://www.hipchat.com/docs/api/method/rooms/show

https://www.hipchat.com/docs/api/method/users/create

https://www.hipchat.com/docs/api/method/users/delete

https://www.hipchat.com/docs/api/method/users/show

https://www.hipchat.com/docs/api/method/users/update

Would be better if they used "/users/new" for "/users/create", HTTP DELETE to 

"/users/{user_id}" instead of "/users/delete?user_id={user_id}", "/rooms/{room_id}" instead of "/rooms/show", and HTTP PUT to "/users/{user_id}" instead of "/users/update?user_id={user_id}."

Also, as for my suggested URL format, let me change that to:

https://api.hipchat.com/v1/rooms/12345/messages/2012-02-01.json?auth_token=asdefasdefasdefasdef

-Mike 

--
You received this message because you are subscribed to the Google Groups "Pinboard" group.
To post to this group, send email to pinboa...@googlegroups.com.
To unsubscribe from this group, send email to pinboard-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/pinboard-dev?hl=en.

[Aristotle Pagaltzis]

Hi Mike,

* Mike Schinkel <mikesc...@newclarity.net> [2012-02-08 01:50]:

> https://www.hipchat.com/docs/api/method/rooms/create
> https://www.hipchat.com/docs/api/method/rooms/delete
> https://www.hipchat.com/docs/api/method/rooms/show
> https://www.hipchat.com/docs/api/method/users/create
> https://www.hipchat.com/docs/api/method/users/delete
> https://www.hipchat.com/docs/api/method/users/show
> https://www.hipchat.com/docs/api/method/users/update
>
> Would be better if they used "/users/new" for "/users/create", HTTP
> DELETE to "/users/{user_id}" instead of
> "/users/delete?user_id={user_id}", "/rooms/{room_id}" instead of
> "/rooms/show", and HTTP PUT to "/users/{user_id}" instead of
> "/users/update?user_id={user_id}."

I would find this even nicer to use:

POST https://api.hipchat.com/v1/users → Create user, returns 303
GET https://api.hipchat.com/v1/users/{user_id} → Get user details
PUT https://api.hipchat.com/v1/users/{user_id} → Update user details
DELETE https://api.hipchat.com/v1/users/{user_id} → Delete user

(But note that PUT is not for partial updates. It has to include the
entire new state of the resource.)

This isn’t even REST, it’s just basic HTTP. (REST is a step beyond – it
means including links to any relevant other parts of the API inside the
responses it returns.)

Maciej: for non-GET/POST methods it’s useful to support accepting them
as POST with a X-HTTP-Method-Override request header or with a special
form parameter that gives the desired actual method to use – so people
who have to use crippled HTTP clients (which includes HTML forms…) or
intermediaries are not locked out.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Mike Schinkel]

Hi Aristotle,

On Feb 7, 2012, at 10:18 PM, Aristotle Pagaltzis wrote:

I would find this even nicer to use:

   POST   https://api.hipchat.com/v1/users → Create user, returns 303
   GET    https://api.hipchat.com/v1/users/{user_id} → Get user details
   PUT    https://api.hipchat.com/v1/users/{user_id} → Update user details
   DELETE https://api.hipchat.com/v1/users/{user_id} → Delete user

(But note that PUT is not for partial updates. It has to include the
entire new state of the resource.)

I like yours even better.  ANd I respect your opinion on all things REST.  (Not sure if you remember me but I spend time on the rest-discuss list in 2006 and 2007.)

This isn’t even REST, it’s just basic HTTP. (REST is a step beyond – it
means including links to any relevant other parts of the API inside the
responses it returns.)

Of course.  

Maciej: for non-GET/POST methods it’s useful to support accepting them

as POST with a X-HTTP-Method-Override request header or with a special
form parameter that gives the desired actual method to use – so people
who have to use crippled HTTP clients (which includes HTML forms…) or
intermediaries are not locked out.

@Maciej: I'll give Aristotle 2 thumbs up for REST APIs, he's been focused on REST for years so he know of what he speaks and you are lucky to have him as a user/developer.  

-Mike