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?
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.
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?)!
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.
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:
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/...`.