
Ask HN: What are the most enjoyable REST APIs you've used? - wkoszek
I want to take a look at some great REST APIs as a reference. I&#x27;m looking to see how stuff like authorization, querying, filters have been implemented etc. SimpleDNS and Stripe look nice. Anything else?
======
KajMagnus
> 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](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...](https://www.vinaysahni.com/best-practices-for-a-pragmatic-
restful-api) — 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/...`.

~~~
wkoszek
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.

~~~
KajMagnus
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. :- )

------
nobody271
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?)!

~~~
wkoszek
Have you worked with any ones you liked?

~~~
nobody271
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.

------
Rjevski
The Twitter API back in 2013 before they destroyed it.

