{"action":"created","issue":{"url":"https://api.github.com/repos/raml-org/raml-spec/issues/192","labels_url":"https://api.github.com/repos/raml-org/raml-spec/issues/192/labels{/name}","comments_url":"https://api.github.com/repos/raml-org/raml-spec/issues/192/comments","events_url":"https://api.github.com/repos/raml-org/raml-spec/issues/192/events","html_url":"https://github.com/raml-org/raml-spec/issues/192","id":114719300,"number":192,"title":"Allow Descriptions/Definitions for Arbitrary HTTP Methods","user":{"login":"ejmr","id":780512,"avatar_url":"https://avatars.githubusercontent.com/u/780512?v=3","gravatar_id":"","url":"https://api.github.com/users/ejmr","html_url":"https://github.com/ejmr","followers_url":"https://api.github.com/users/ejmr/followers","following_url":"https://api.github.com/users/ejmr/following{/other_user}","gists_url":"https://api.github.com/users/ejmr/gists{/gist_id}","starred_url":"https://api.github.com/users/ejmr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ejmr/subscriptions","organizations_url":"https://api.github.com/users/ejmr/orgs","repos_url":"https://api.github.com/users/ejmr/repos","events_url":"https://api.github.com/users/ejmr/events{/privacy}","received_events_url":"https://api.github.com/users/ejmr/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-11-03T00:53:59Z","updated_at":"2015-11-03T18:03:01Z","closed_at":null,"body":"First please see my comments on #95.  The HTTP/1.1 specification allows servers to implement arbitrary methods but these are not possible to describe in RAML 0.8.  [Here is a personal use-case for defining new HTTP methods](http://ericjmritz.name/2015/10/22/defining-custom-http-methods/).  I wanted to use RAML for that project, but as it is the lack of support for arbitrary HTTP methods made it impossible to use.\r\n\r\nIgnoring my own use-case though, in general I think it is a mistake for RAML to restrict support for HTTP methods in any way, e.g. supporting only a fixed list of methods.  This puts RAML in contrast with section 5.1.1 of the HTTP/1.1 standard, making it impossible to describe certain APIs with RAML which are perfectly acceptable and valid under RFC 2616.\r\n\r\nI have not yet tried modifying one of the various RAML tools to patch in support for arbitrary HTTP methods though, so I don't have a technical solution to present at the moment.  My general idea is that wherever RAML allows things like `/get` or `/post`, it should accept `/foo` where `foo` could be any name that could be a valid HTTP method name."},"comment":{"url":"https://api.github.com/repos/raml-org/raml-spec/issues/comments/153436638","html_url":"https://github.com/raml-org/raml-spec/issues/192#issuecomment-153436638","issue_url":"https://api.github.com/repos/raml-org/raml-spec/issues/192","id":153436638,"user":{"login":"ejmr","id":780512,"avatar_url":"https://avatars.githubusercontent.com/u/780512?v=3","gravatar_id":"","url":"https://api.github.com/users/ejmr","html_url":"https://github.com/ejmr","followers_url":"https://api.github.com/users/ejmr/followers","following_url":"https://api.github.com/users/ejmr/following{/other_user}","gists_url":"https://api.github.com/users/ejmr/gists{/gist_id}","starred_url":"https://api.github.com/users/ejmr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ejmr/subscriptions","organizations_url":"https://api.github.com/users/ejmr/orgs","repos_url":"https://api.github.com/users/ejmr/repos","events_url":"https://api.github.com/users/ejmr/events{/privacy}","received_events_url":"https://api.github.com/users/ejmr/received_events","type":"User","site_admin":false},"created_at":"2015-11-03T18:03:01Z","updated_at":"2015-11-03T18:03:01Z","body":"> How are custom methods defined? Are they restricted to have a request/response body, etc. like every other method?\r\n\r\nCustom methods are defined by the server, which is to say the server has the \"authority\" to tells clients what is a method and what isn't, which is done using the `Allow` response header; it lists all of the methods valid for any given URI.  Generally (although not required) `OPTIONS` will return the `Allow` header, which will be something like...\r\n\r\n    Allow: OPTIONS, HEAD, GET, PUT\r\n\r\n...which clients can use to recognize what methods are allowed for that entity.  When a `PUT` request creates a new entity the server *should* (in the RFC 2119 sense) return an `Allow` header listing all acceptable methods for that entity; the standard doesn't make this mandatory though.  `Allow` is the only way a server can tell clients about custom methods.  And the only situation where the server **must** (again RFC 2119) return the `Allow` header is when it sends a `405 Method Not Allowed` response, which somewhat ironically makes that the best way for a client to \"discover\" the existence of a method.  I quote \"discover\" specifically to highlight that the HTTP/1.1 standard, with regard to custom methods, is designed around the idea of both the server and client being ignorant of what methods are available.  So those custom methods are \"defined\" essentially to the extent that they are made discoverable by the server supporting them.\r\n\r\n> Are they restricted to have a request/response body, etc. like every other method?\r\n\r\nCustom methods are required to have the `Host` header, which all HTTP/1.1 methods must have, but that's it.  They are not required to have a response body, in which case the server would return something like `204 No Content` for a successful request involving a custom method that doesn't produce a response body.  But their responses can have bodies, in which case they would have the usual headers describing the content type, etc., to give the client as much information as possible about what the server is sending back."}}