Support custom HTTP verbs

[elliotttf]

I am building an API that will support a PURGE method, similar to how some caches do (e.g. varnish) but the apiary blueprint seems to be ignoring these methods. For example:

### Purge a cached listing [PURGE]

+ Request

    + Headers

            Accept: application/json

+ Response 204

will not be displayed in the correct blueprint section. It looks like the blueprint is ignoring non-standard verbs as changing PURGE to PATCH, PUT, etc will display it as expected. Would it be possible to add support for custom verbs?

[klokane]

It is due to https://github.com/apiaryio/snowcrash/blob/master/src/HTTP.h#L22

Can you specify what do you mean by "custom verbs"? Just add another few word to "allowed set"? We can go to similar problem for another verbs.

Maybe we can allow everything, with optional warning to according to HTTP specification?

@zdne do you see there some reason to do not allow any verb? There can be some limitation like "one word", "UPPERCASE" etc.

[zdne]

Hmm this is interesting. I am afraid picking this up on UPPERCASE would be too generic. But the answer is yes, I believe we should support custom Methods.

Perhaps we should introduce a keyword to explicitly mark these definitions e.g.

### Action Purge a cached listing [PURGE]

+ Request

    + Headers

            Accept: application/json

+ Response 204

Thoughts?

[klokane]

I strongly agree about support custom keywords.

I mean, limitation to:

• enclose in [] parenthesis
• UPPERCASE
• one word
• maybe - enclose line???

should be enought to identify as method name?

I'm afraid to "Action" keyword is relative restrictive (oposite to current blueprint action rules)

[pksunkara]

Instead of introducing Action keyword, why not support a metadata key which will the allow the user to define custom verbs? For example, in the above case, the API Blueprint would be

FORMAT: 1A
HTTP-VERBS: PURGE, RANDOM

### Purge a cached listing [PURGE]

+ Request

    + Headers

            Accept: application/json

+ Response 204

[honzajavorek]

@pksunkara that's quite neat, nicely explicit.

[klokane]

@pksunkara like this idea

[pksunkara]

Yeah, we have been neglecting metadata for too long. :smile:

[fosrias]

I think it should just be "CUSTOM_VERBS" to be more forward compatible with other protocols.

[kylef]

I don't think the word "Verbs" should be used, it's never described as this in the HTTP specification (9) but instead called "Methods".

[fosrias]

Well, technically, from a REST/Protocol independent standpoint we are talking about the uniform interface. Neither verbs or methods are used in the REST uniform interface definition. That being said, CoAP references methods as well, so :+1: for "CUSTOM_METHODS".

On Fri, Feb 13, 2015 at 10:02 AM, Kyle Fuller [email protected] wrote:

I don't think the word "Verbs" should be used, it's never described as this in the HTTP specification (9) https://www.ietf.org/rfc/rfc2616.txt but instead called "Methods".

— Reply to this email directly or view it on GitHub https://github.com/apiaryio/api-blueprint/issues/147#issuecomment-74297435 .