Custom HTTP methods

[Danack]

Hi there!

For an API we're building, one of the api end-points we need to expose doesn't fit well within the normal HTTP methods/verbs.

Is it possible to tell swagger-php about non-standard methods so it can generate the appropriate swagger api json for them?

I had a look but it seems that they are hard-coded here, and I can't see a way to plug any other types in.

cheers
Dan

[bfanger]

The swagger spec defines only has the standard verbs for a path

Too generate swagger output with custom verbs you'l need to create an annotation that extends from Path and patch Swagger.

class CustomPath extends Swagger\Annotations\Path { ... }
class CustomMethod extends Swagger\Annotations\Operation { ... }
Swagger\Annotations\Swagger::$_nested['CustomPath'] = ['paths', 'path'];

/**
 * @CustomPath(path="/some/path", @CustomMethod(description="really special"))
*/
function reallySpecial() { ... }

This might work, but it's not valid swagger output.
I would really advice against using non-standard methods, think of you api of exposing resources which you can create (POST), update (PATCH), replace(PUT) or delete(DELETE). If your building a RPC style api just use POST. If you trying to document a websocket / event-stream i'm not sure if swagger is a good fit for now.

[Danack]

Thanks for the answer.

I would really advice against using non-standard methods, ....If your building a RPC style api just use POST.

Just to explain the reasoning, the exact operation is a clone/copy of an existing resource......using POST for that seems misleading, as POST has it's own clear meaning. Allowing a custom* method of COPY seems to make the API a lot more intuitive:

POST /foo/123 - people would expect this to update foo with id of 123
COPY /foo/123 - people would expect this to return a new foo

The swagger spec defines only has the standard verbs for a path

Oh darn. We're actually also going to be using other tools that consume the Swagger spec JSON....they're unlikely to be happy with custom verbs.

• COPY has been registered http://www.iana.org/assignments/http-methods/http-methods.xhtml so isn't completely bespoke.

[bfanger]

Thanks for the explaination, I'd personally would go for POST /foo/123/clone or POST /foo/123/create-clone is this case

[Danack]

Yeah, I'll almost certainly do that.

I also just realised that the COPY verb actually doesn't have the correct semantics either, as for WEBDAV where it apparently comes from, you have to send an id to copy it to, and COPY is meant to be idempotent.

A CLONE method wouldn't be idempotent, and the client wouldn't know the id before the clone...so yeah, give up and use ~~~tables~~~ POST.