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?
> authorization<p>Hmm. Is authorization maybe very app specific? Did you mean <i>authentication</i>?:<p>Basic Authentication and API keys and HTTPS seems popular. E.g. Stripe: <a href="https://stripe.com/docs/connect/authentication#api-keys" rel="nofollow">https://stripe.com/docs/connect/authentication#api-keys</a>, and Chargebee (they deal with tons of money).<p>I like this article: <a href="https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api" rel="nofollow">https://www.vinaysahni.com/best-practices-for-a-pragmatic-re...</a> — except that I use only POST and GET, never PUT, DELETE etc. And name the endpoints like:<p><pre><code> 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
</code></pre>
then one knows what and endpoint does, by just looking at the URL path. Won't also need to ask: "But which method?"<p>Also, most people that actually design APIs, seem to put the API version in the URL, like `/api/v1/...`.
Not Facebook. Not Disqus either. Not Google sheets. Oh, yeah, and definitely not Ebay.<p>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.<p>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.<p>A good interaction to get a users photos should look like this:<p>- /get-all-photos/userId<p>That returns a JSON object with everything you need to know about the users photos.<p>For example: the ONE url to the photo, title, caption<p>Oh, and no paging and dont you EVER phone home in some weird alien way (embed a .gif to communicate, what?)!