Replace the hardcoded {format} parameter with media type negotiation through an “Accept” header

[Rinzwind]

Swagger seems to assume that resources have a URL with a {format} path parameter which can be “json” or “xml”, like “/pet.json/1” or “/pet.xml/1”. I'm still pretty new to REST API design, but from what I understand from reading the O'Reilly “REST API Design Rulebook" including such a format parameter in the URL isn't considered good REST design as it assigns two different URLs to what is really the same resource (but in two different representations). The relevant rule in the book is “Rule: File extensions should not be included in URIs” which appears on page 13. The author recommends that “REST API clients should be encouraged to utilize HTTP’s provided format selection mechanism, the Accept request header ... when multiple representations are available.”

[fehguy]

Hi @Rinzwind, two things. First off, the UI doesn't require the .{format}--you can try out examples for yourself by pulling the swagger-core samples and running them. I'd recommend this one:

https://github.com/wordnik/swagger-core/tree/1.1.0-spec/samples/scala-jaxrs-no-format

Where if you pass "content-type:application/json" in the Accept headers, you'll get JSON. If you pass "content-type:application/xml" you'll get XML.

The point about it being better "restful" design really depends. The nice thing about the .{format} notation is that it's both explicit and clear what you're expecting. Twitter pioneered this with their API because they found that clients simply don't always send the right info to the service and it causes confusion.

So the Swagger philosophy is that, it works either way, and the exact REST semantics that you use will be somewhat transparent to the user, via swagger-ui and swagger-codegen.