Better example for the Resource Names about http-api-design

[geemus]

@keithamus I certainly can see how that is confusing, thanks for the suggestions. The intention was basically to outline /account specifically, as presumably this gets you YOUR account and you are not allowed to access other peoples. That said, that is a big assumption and not super clear. /status seems like it could be a good candidate for a clearer option. Would you be up for reworking that verbiage to clarify in a pull request? Thanks!

[hkdobrev]

Perhaps a clearer example of a singleton API is /status, or /search.

I don't think /search is a good example as it returns multiple items instead of a single one. Therefore it's not a singleton.

Search could be achieved with something like this (if you search for same type items e.g. products): /products?query=watch

[geemus]

@hkdobrev I hadn't considered the multiple return items, but would agree that search/query has the possibility of being much more complicated for a lot of reasons (and therefore probably not the best choice of example).

[geemus]

@keithamus hey, sorry about not getting back to us. /status could still improve things, any particular reason to close?

[keithamus]

Issue is quite old now, I closed it to clean out my personal issues page. Feel free to re-open if you want to.

[geemus]

Thanks for the clarification, better late than never.

[keithamus]

Ah sweet! Thanks @geemus. Enjoy the rest of your day 😄

[geemus]

Thanks, you too!

On Mon, Jan 25, 2016 at 1:55 PM, Keith Cirkel [email protected]
wrote:

Ah sweet! Thanks @geemus https://github.com/geemus. Enjoy the rest of
your day [image: 😄]

—
Reply to this email directly or view it on GitHub
#39 (comment)
.

[crazytonyi]

What about /system as a singleton? If it refers to the application itself as a resource, there would only be one. But on that train of thinking, would such a resource be accessible beyond a GET? It likely wouldn't be something that gets created or deleted. Even a PUT to update it seems semantically dodgy. So OPTIONS for such a resource should only return GET, PATCH. Thoughts?

[geemus]

@crazytonyi good question. I suppose that could potentially be another example as there should only be one "self" in the system context. I think the status example works reasonably well for similar reasons (it is, in effect a single property of the system). And it more clearly has updates/etc, though perhaps still not deletes. I dunno, maybe the fact that it is hard for us to think up good examples is an indication that singletons are somewhat of an anti-pattern anyway.