Would you be pissed if we removed automatic format switching based on "file extension" in the url (.json vs .xml, etc)?

[Adam Tuttle]

From the beginning, Taffy has allowed you to support multiple return data formats and allow your consumers to specify which one they want back by appending the equivalent of the "file extension" to the URL; as in:

http://api.example.com/users.json

http://api.example.com/users.xml

http://api.example.com/users.yaml

It turns out that this is kind of anti-REST... in as much as it breaks the concept of resources (URI) and ignores the HTTP Accept header. This is an issue that has surfaced while trying to find a solution to this bug.

In fact, in the presentation I'll be giving at cfObjective in a few short hours, one of the anti-patterns that I list is ignoring things that HTTP provides for you (Using post for all requests instead of the various verbs, for instance). Taffy already supports using the Accept header, but for convenience it also followed the trend of "file extensions" in the url, which makes it easy to test using nothing but a web browser as your client.

This hypothetical change -- removing the convenience of "file extensions" in the URL and requiring the Accepts header to get a response using a format other than the default -- would mean that it would not be as easy to do basic testing by just putting resource URLs into the browser's location bar. That said, Taffy does provide a client mocking utility in the dashboard, so that would get you part way there -- but it doesn't currently have a way to specify request headers, so that would need to be added. (Heck, maybe make it easy by just using a dropdown for the response format).

This could be a significant change, and it would definitely not be considered backwards compatible, so for that reason alone any version with the change should increase the "major" version of the framework (so 2.x). Since it would be in 2.0, I could defer it for a while and work on some other bugs for 1.2 before releasing 2.0 -- or I could just move those bugs to the 2.0 target too. But that's not all that important and I'm probably just rambling because it's after 1am local time, 2am in my home TZ, and I'm starting to lose touch with sanity.

What's important to me is the opinions of you, the users. Would removing this functionality and requiring clients of your APIs to use the Accepts header to specify a non-default return format cause you greif? Would it piss you off or otherwise sour your opinion of Taffy? Most importantly, would you continue to use Taffy?

Thanks for the feedback!
Adam

[Steve Rittler]

I would have no problem with this change - I don't use this feature in my apps at the present time.

steve

--

-------
Steve Rittler
scri...@gmail.com

[Amy Ortwein]

I was finding it handy in testing but, in most situations I've come up
with so far, I'm going to need things returned in a specific format
but it may not be the default format (image, rss feed formatted xml
that can plug into cffeed). I found myself relying on the .extension
format rather than having things return in the format that was
required of it.... In some situations like using img src= for example,
I would not want to be stuck having to deal with headers when sending
out my get request... So what I'm saying is, I would not have a
problem with losing the extension and adding in header based return
format, as long as there's a way to specifically define the return
format for special cases when I don't want the default formatting to
be returned, and can't really mess with headers.

Does that make sense?

Good luck on your presentation.

On May 13, 7:39 am, Steve Rittler <scritt...@gmail.com> wrote:
> I would have no problem with this change - I don't use this feature in my
> apps at the present time.
>
> steve
>
>
>
>
>
>
>
>
>
> On Fri, May 13, 2011 at 2:09 AM, Adam Tuttle <a...@fusiongrokker.com> wrote:
> > From the beginning, Taffy has allowed you to support multiple return data
> > formats and allow your consumers to specify which one they want back by
> > appending the equivalent of the "file extension" to the URL; as in:
>
> >http://api.example.com/users.json
> >http://api.example.com/users.xml
> >http://api.example.com/users.yaml
>
> > It turns out that this is kind of anti-REST... in as much as it breaks the
> > concept of resources (URI) and ignores the HTTP Accept header. This is an

> > issue that has surfaced while trying to find a solution to this bug<https://github.com/atuttle/Taffy/issues/35>
> > .

> scritt...@gmail.com

[Matthew Gersting]

I like using that feature quite a bit, but at the end of the day I like being a bit of a REST stickler so I can understand the reasoning. 

Out of curiosity, is there any reason using a query string value to control the output type is frowned upon? If not, could be cool for each taffy instance to have a configuration option to auto check for that parameter. 

[Barney Boisvert]

It seems like a reasonable half-way would be to deprecate
extension-for-format usage, and if an extension is used without an
Accept header (which should supercede an extension), issue a
deprecation warning in a response header. That way you retain your
backwards compatibility, and the warning would be fairly obvious
(while remaining zero-effect) since if you're using a RESTful API,
you're going to be looking at your raw responses.

chers,
barneyb

--
Barney Boisvert
bboi...@gmail.com
http://www.barneyb.com/

[Matt Gersting]

Adam,
Wanted to check in re: this thread before I got to far down the road.  I like the sound of Barney has suggested.  Did you ever make a decision about how this is going to be implemented?

[Adam Tuttle]

Hi Matt,

At this point I'm focused (when time allows) on getting 1.1 out the door; with just a few kinks in Railo compatibility to finish before releasing it. Once that's done I'll revisit this thread when planning for 2.0.

If I ultimately decide to remove the feature, I'll take at least two minor versions to do it, so that in 1.3+ a deprecation warning would be issued, as Barney suggested, and then in 2.x it wouldn't be supported at all.

Adam