Hacker News new | past | comments | ask | show | jobs | submit login

Nice rules, except for #7. Class names are singular, as are most SQL tables in modern SQL. I think this pattern should be followed also in URL design, since it’s more common to refer to a single at /person/327 than the list of all people at /person.

However, everyone designing an API should be aware that the REST principles really don’t work very well without HATEOAS, and HATEOAS does not require any “designed” URLs, just that URLs be persistent. Any client to a real REST (HATEOAS) API requires exactly one URL, the root. All other URLs should be discovered by the clients by links in the resources given by the API, starting with the resource present at the root URL.




I actually think the singular/plural question isn't too important - the key thing is that it's consistent across the whole API.


I think that discoverability is overrated, because you can discover URLs (as in, what options are available) but you can't discover what exactly those URLs will do (especially for non-GET options) or find URLs that will do exactly what you need, so any discovered URLs aren't usable anyway unless you already knew beforehand what exactly you are trying to discover.

The client (if it's not a human) can't magically discover the semantics, and a HATEOAS API can't properly describe the semantics - it will give you a relationship type string that might be descriptive of what the URL will do, and that's it.

In any case, you need to define a mapping between "I want to do X" and an item on the server side; and when writing a client there's not much practical difference (only a conceptual one) between linking "do X" to an URL string versus linking "do X" to a HATEOAS relationship string. You gain some stability if the service renames some methods, but unless you're really sure that it was just a cosmetic change and none of the semantics has changed, you need to re-verify everything anyway if it happens.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: