Narrow down the list of supported HTTP methods/verbs

[nohorbee]

RAML 1.0 should narrow the list of supported HTTP methods to:

• GET
• HEAD
• POST
• PUT
• DELETE
• PATCH

Rationale:

(The first 5 as defined in RCF2616 and RFC7231, the last one as defined in RFC5789) Thus removing the following 3 methods which have no clear semantics in an REST API:

• CONNECT: RFC7231 reads:

  CONNECT is intended only for use in requests to a proxy. An origin server that receives a CONNECT request for itself MAY respond with a 2xx (Successful) status code to indicate that a connection is established. However, most origin servers do not implement CONNECT.

• TRACE: has no value for a REST API as it is an echo type of request and is valuable for debugging integration/transport/proxying issues, not to carry API semantics.
• OPTIONS: We might want to revisit the applicability of this method to provide a mechanism for describing APIs, but generally this method does not carry API semantics.

[lowema]

I would be reticent to remove the OPTIONS verb. We see it as a good way to return the RAML itself, thus giving an API a kind of discovery mechanism when using this verb against the API itself. This would allow all manner of tools to interact directly with the REST endpoint to discover the way the API works.

I believe this is what was intended by the use of this verb, it would be a shame not to use it in the spirit it was intended for !

[michael-murphree]

+1 for keeping OPTIONS. It would be a shame not to be able to describe a legitimate use of the verb in a language for describing the API.

[sichvoge]

The current draft will consider all common HTTP verbs such as get, patch, put, post, delete, head, and options as well.

[lowema]

We shouldn't limit what people want to utilise in their designs. If there's a use case that somebody wants then we shouldn't restrict them. This behaviour is likely to restrict adoption.

[sichvoge]

Completely agree @lowema

[usarid]

As @sichvoge commented, we will have OPTIONS, so the only ones being removed are connect and trace. Neither seem remotely relevant to an API call.

CONNECT is used to negotiate transport-level concerns, such as establishing websocket tunnel connections.

TRACE is an echo generator that allows for no body, and it isn't clear how it could relate to the API: because an API spec describes behavior on specific methods, and you don't specify another method in making a TRACE request, you're not even echoing what the server received from any API request -- it's literally just a type of general ping.

So it seems incompatible with the goal of describing an API to incorporate these two methods into its contract.

[ejmr]

I was looking for a way to use custom HTTP methods with RAML and then came across this issue. The HTTP 1.1 standard allows servers to support custom methods, which they can tell clients about via the Allow header field; see RFC 2616 section 5.1.1. Thus RAML should not, in my opinion, narrow down the list of HTTP methods, and moreso should allow authors to define APIs using custom HTTP methods. Is there already someway to do this by any chance? E.g. define a resource that accepts the RESET method.

[sichvoge]

That is an interesting use case. I haven't seen the requirements before, but how does something like that looks like? Do you have an example?

[ejmr]

Do you have an example?

Yeah, I recently described a situation where I'm using a custom HTTP method.