Ask HN: What are the most enjoyable REST APIs you've used? | Hacker News Reader

Ask HN: What are the most enjoyable REST APIs you've used?

2 pointswkoszek7 comments

I want to take a look at some great REST APIs as a reference. I'm looking to see how stuff like authorization, querying, filters have been implemented etc. SimpleDNS and Stripe look nice. Anything else?

View on HN

> authorization

Hmm. Is authorization maybe very app specific? Did you mean authentication?:

Basic Authentication and API keys and HTTPS seems popular. E.g. Stripe: https://stripe.com/docs/connect/authentication#api-keys, and Chargebee (they deal with tons of money).

I like this article: https://www.vinaysahni.com/best-practices-for-a-pragmatic-re... — except that I use only POST and GET, never PUT, DELETE etc. And name the endpoints like:

    POST  /-/create-page            controllers.PageController.createPage
    POST  /-/pin-page               controllers.PageController.pinPage
    POST  /-/unpin-page             controllers.PageController.unpinPage
    POST  /-/reply                  controllers.ReplyController.handleReply

    GET   /-/load-draft-and-guidelines controllers.EditController.loadDraftAndGuidelines
    GET   /-/load-draft-and-text    controllers.EditController.loadDraftAndText
    POST  /-/edit                   controllers.EditController.edit

then one knows what and endpoint does, by just looking at the URL path. Won't also need to ask: "But which method?"

Also, most people that actually design APIs, seem to put the API version in the URL, like `/api/v1/...`.

I'm wondering whether what you showed here is REST. I maybe meets some indempotent guidelines, but it should be something more standard like:

``` /pages/ POST create a page /pages/{id} PUT update a page /pages/{id} GET get a page ```

as looking at some standard JS code, if you stick to this theme, you will some functionality for free, like getting an array of items after GET is done for you etc.

Hmm yes right now I'm not sure if it's strictly REST or not :- )

I keep forgetting exactly what REST means. The web app is happy and the ones who use it too, even if ... maybe not strictly REST. :- )

Not Facebook. Not Disqus either. Not Google sheets. Oh, yeah, and definitely not Ebay.

To me a good REST API makes getting started easy. If I spend the first few hours with your framework trying to get oauth setup that's not a good sign.

Second way, imo, to design a good API is to not be pretentious. We should be able to guess where to look for things without having to learn any $5 words.

A good interaction to get a users photos should look like this:

- /get-all-photos/userId

That returns a JSON object with everything you need to know about the users photos.

For example: the ONE url to the photo, title, caption

Oh, and no paging and dont you EVER phone home in some weird alien way (embed a .gif to communicate, what?)!

Have you worked with any ones you liked?

No, lol. I like the way asp.net urls are supposed to work. That is, simple routes in plain english. It never works out that way though. I think the end goal should be to make it as easy on the user as possible. So to me that means doing any heavy lifting possible so the user doesn't have to.

Just think about paging. As soon as I see paging I know I have to create a whole JavaScript state machine to keep track of the index and etc. I think that's hostile to the user. Give me everything even if it's just an array of ID's so that I dont have to make that state machine.

Another example I gave was having multiple urls for the same image. I really do not think that's practical. If you need something like a high definition download put that in its own section of the API. For 99.9% of use cases the normal image will do.

Just K.I.S.S. Before you write anything stop and think if you can say it in a more plain way.

The Twitter API back in 2013 before they destroyed it.

Reply on news.ycombinator.com