Improve generation of HTTP API reference #27
Conversation
* Document how to send the multiparts for /add * Bring markdown geneartion in line with ipfs-docs-v2 * Ignore client-side options * Set curl -X POST * Do not list args of type File in arguments * Improve some formatting This still leaves things at 0.4.22 so that then we can get a clean diff of changes for 0.4.23 and eventually for 0.5.0. Fixes #25 Fixes #4
…scriptions Co-Authored-By: Steven Allen <[email protected]>
markdown.go
Outdated
| internally for some reason. To know that reason, you have to look at the | ||
| "application layer" error (usually returned with the body of the command). In | ||
| the case of streaming endpoints, they always return 200 before starting to | ||
| stream the response. Any errors are included as Trailer response headers. |
There was a problem hiding this comment.
If we return an error before we start streaming, I think we may return a 500.
It's simpler to just say that 4xx are transport-level errors. For application level errors, you may either receive a 500 error code if the error is detected early, or a 200 response plus a trailing error if it's detected late.
There was a problem hiding this comment.
I want to avoid talking about transport layer vs application layer as that may not be understandable for some users. I gave it another try and tried to explain this case.
Co-Authored-By: Steven Allen <[email protected]>
|
Looks good!
|
Last time I checked (3 years ago), Swagger or apiary did not play well with our API. We have endpoints that support streaming and not streaming, we have multiparts, we have things that take protobufs as input, we have things that take json. Things are just not overly like the writers if RESTful API specs assume they are. The effort to just write an accurate swagger spec for this API is gigantic, only to maybe find that at the end it cannot produce accurate docs. Additionally, the effort to maintain a swagger spec and keep it aligned is also gigantic. Therefore, given that we have a one-click way of producing docs out of the actual code, and that this has saved us many developer hours and is mostly accurate, I take every chance to repeat that I am against the swagger approach for impractical, even if the current spec version would somehow be proven to accommodate all our API choices. I wish things were different though.
Yeah! |
|
Moving forward with this, can address anything else later. |
This still leaves things at 0.4.22 so that then we can get a clean
diff of changes for 0.4.23 and eventually for 0.5.0.
Fixes #25
Fixes #4