> In any context, documenting every function is good practice.
If your API is procedural (is RPC), then yes, procedures being your core abstractions that's what you document.
But REST is not procedural, the core RESTful abstraction is the resource and it is that resource which provides state transitions from itself (to itself or to other resources). In HTTP these transitions are a triplet of (method, URI[, body]) but that's incidental.
Because the core abstraction of REST is the resource, resource types (or media types) is what you document, and the possible transitions from a media type are documented as part of that media type (more precisely, the media type's documentation indicates what the transition hookpoints are — for instance in HTML they're <link>, <a> and <form> — and what the semantics of those hookpoints are relative to the resource — if any).
To clarify, I have absolutely no issue with your goal of documenting your API and every endpoint of your API, I just take issue with your claim of documenting RESTful APIs when the very structure of your tool and production preclude any possibility of RESTfulness.
If your API is procedural (is RPC), then yes, procedures being your core abstractions that's what you document.
But REST is not procedural, the core RESTful abstraction is the resource and it is that resource which provides state transitions from itself (to itself or to other resources). In HTTP these transitions are a triplet of (method, URI[, body]) but that's incidental.
Because the core abstraction of REST is the resource, resource types (or media types) is what you document, and the possible transitions from a media type are documented as part of that media type (more precisely, the media type's documentation indicates what the transition hookpoints are — for instance in HTML they're <link>, <a> and <form> — and what the semantics of those hookpoints are relative to the resource — if any).
To clarify, I have absolutely no issue with your goal of documenting your API and every endpoint of your API, I just take issue with your claim of documenting RESTful APIs when the very structure of your tool and production preclude any possibility of RESTfulness.