from Hacker News

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

by wkoszek on 10/4/18, 12:17 AM with 7 comments

• by KajMagnus on 10/4/18, 4:11 AM

  > 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/...`.

• by nobody271 on 10/4/18, 1:02 AM

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

• by Rjevski on 10/5/18, 10:20 AM

  The Twitter API back in 2013 before they destroyed it.