Guidelines are redefining PUT semantic

[ioggstream]

I expect

HTTP methods semantics should be expressed in https://tools.ietf.org/html/rfc7231

Not to be redefined https://github.com/ongov/API-Guidelines/blame/master/API-Guidelines.md#L184

Instead

Guidelines seem to forbid PUT + 201 Created see https://tools.ietf.org/html/rfc7231#section-4.3.4

[AofH]

The guidelines do not forbid the creation of the resource during a PUT request. The document is aimed at people who may not be familiar with web API's and it is potentially confusing to them when POST explicitly handles the create. Eventually there will be more detailed guides which discuss areas in detail which would discuss what you brought up here.

[ioggstream]

Hi @AofH, thanks for your replies!

The document is aimed at people who may not be familiar with web API's
and it is potentially confusing to them

I understand. My suggestion is trying to adapt the contents of
the upcoming http specifications.

There has been some discussion on that kind of statements and the new http-semantics (currently in draft) tries to address that.

Generally, there's this new draft on Best Current Practices for protocols based on http which - while it's targeted to RFC editors - may be useful