undefined | Better HN

0 pointsa_c_s11y ago0 comments

Sure, that sounds nice in theory. In the wild, how many developers (especially those working on internal APIs) have the time & inclination to thoroughly document their entire APIs? And if it exists, many developers read the entire spec of an API before beginning development? In my experience both are rare.

Given the constraints developers often find themselves under, having an API that uses common patterns most developers already understand has great value. (Ex. 'GET /customer/123' performs a safe retrieval of a representation of the customer with ID 123, no documentation required)

This leaves both developers (API creator & API consumer) free to focus on documenting/understanding the non-trivial parts of the API rather than reinventing the wheel.

0 comments

2 comments · 1 top-level

dragonwriter11y ago· 1 in thread

Note that this use of conventional URI structure patterns does have the value you describe, but is also completely orthogonal to REST (REST isn't about beautiful URIs -- the path part of the URI could all be UUIDs and you could follow the REST architectural style perfectly; HATEOAS, in particular, means that other than the entry point, your URIs should all be coming to you from other documents with their context in that document telling you what they are, so you don't need to parse the URI for meaning.)

a_c_sOP11y ago

Yes, there is a difference betwixt 'true REST' (as defined by Roy Fielding in his PhD dissertation) and what most people refer to as REST. I was referring to the latter: in my experience 'true REST' APIs are rare in the wild.

j / k navigate · click thread line to collapse