OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Proposal: Support for LINK and UNLINK HTTP methods
Hi, I working on an app which has a REST interface where I use LINK and UNLINK HTTP methods to send messages. I would like to use swagger for documentation purposes, but unfortunately it does not support these two method types. Have you considered the support of these? RFC: http://tools.ietf.org/id/draft-snell-link-method-01.html
Regards, Grunci
Here is the real RFC (HTTP 1.1), not a draft: https://tools.ietf.org/html/rfc2068#section-19.6.1
And the IANA registry of all HTTP methods: https://www.iana.org/assignments/http-methods/http-methods.xhtml
RFC2616 which obsoletes RFC2068 says about PATCH/LINK/UNLINK:
The PATCH, LINK, UNLINK methods were defined but not commonly implemented in previous versions of this specification.
But this RFC is dated of year 1999. Since, REST APIs and are born and PATCH/LINK/UNLINK become really useful. As Swagger already has support for PATCH, I don't see a reason to not support LINK/UNLINK too.
The latest draft (as the name implies this is work in progress) about LINK/UNLINK: https://tools.ietf.org/html/draft-snell-link-method-12
Thx to @dolmen, nodejs http parser supports LINK & UNLINK https://github.com/nodejs/http-parser/commit/e557b62744e4f487a303b25b27c56947d7a8bacc
When do you think the support of these HTTP methods can be available in swagger?
They won't be added to the current swagger-spec (that wouldn't make any sense) but they can be considered for the next one.
May I ask, how often do you create a new swagger spec? I just would like to know some info regarding the 'when' question.
Thx
historically, roughly every year we have a new spec. Recall all tooling needs to be updated with each change to the spec.
I would like to vote htis one up, but I don't see any use in limiting this to link/unlink. Why not allow any custom HTTP method (except for a select few reserved words)?
As long as the browser can send it, it should be documentable imho.
@dolmen @grunci: Do you have an example of an API where it is used? I've looked at RFC 2068, and the text there doesn't give me enough information on how the new links (or the removed links) are being transferred.
That might be one of the reasons for it not being implemented widely ;-)
At showpad we use these in combination with a Link: header. We pretty much follow http://tools.ietf.org/id/draft-snell-link-method-01.html
