New Taffy Dashboard - I/O Docs, Swagger or go for something else?

[Marco Betschart]

Hi Folks!

I'm currently keen on developing a new dashboard for Taffy which makes using it more easy and has a bigger benefit for application developers which may not be directly involved in developing your API.

As you can see here: https://github.com/atuttle/Taffy/issues/84 I've currently gave Swagger a go.

At my level of implementation I'm a bit lost in space for now because I'm facing a few issues I'd like to share and get your thoughts on it:

1) Adding new Taffy meta data

To fully support the Swagger specification we may add additional taffy meta data such as "taffy:allowableMultiple" or "taffy:dataType" as you can see over here: https://github.com/wordnik/swagger-core/wiki/parameters

2) Support for authentication methods

In the Swagger specification I can't see any possibility to add protected methods to the responses. I'd really love to add OAuth protected methods, methods which are protected by API key or methods which are protected by anything else. As I've seen this would be possible by using I/O Docs and the "auth" key: https://github.com/mashery/iodocs

3) Running the dashboard directly in the browser

My idea of the dashboard is that I can just open it up in my browser and execute the API calls. Therefore if your API is reachable on http://api.yourdomain.com/v1 you can just open up this URL in the browser and start testing the API. As I/O Docs runs as a node.js Application, I can't see how this could be done with it?!

4) As of the limitations in specification of Swagger and I don't know how to use I/O Docs directly in the browser there may be another solution to achieved the desired result?!

I'm open for any suggestions to put the new dashboard further.

[Adam Tuttle]

#1: I think adding new metadata in support of swagger/documentation is fine. Let's just not make it required for anything other than the dashboard (without further discussion).

#2: My limited understanding of OAuth is certainly impeding my thought process, but I don't really see a good way to bake this into the dashboard. Maybe the thing to do is to detect that the request is coming from the dashboard and disable the auth checks in that case, somehow?

#3: If IODocs requires Node, then that's a non-starter.

#4: The dashboard is desperately in need of an overhaul, so even if we can't bake in the OAuth/authenticated resource support, basing it on Swagger will definitely be a big step up.

</$0.02>
Adam

[Marco Betschart]

Thanks for your response Adam. Here my thoughts on your points:

1) I'm absolutely agree with you on this and I wont just modify taffy meta data things without further discussion. The only thing is, which names to choose as you can see over here there was already a discussion about authentication and metadata:

https://groups.google.com/forum/?fromgroups=#!topic/taffy-users/4C8R7_-olrU

2) In my understanding the dashboard should not be used just by the API developer for testing the endpoints. I think it's a great tool to provide a fully usable API documentation at no costs. Therefore I'm keen on running the dashboard on the main URL without requiring any further parameters. So application developers (instead of API developers) could use this one to understand how the API works and build their applications on top of it. That's why I think just disabling authentication methods is not an option, since this would open up the doors for anybody to use every API method on production systems as they like to. I've a fair good understanding of OAuth and how it works. So the dashboard may only provide the ability to put into an oauth_token and an oauth_token_secret and use these for the secured API requests - that's it.

3) I'm not sure if it absolutely relies on Node - I'll ask the guys over at mashery to give me a hand on this one.

4) Please do not missunderstand, OAuth isn't a requirement at all for me!! The only thing I want to ensure right now, is to walk the right line. And as I've not seen any possibility yet to add an authentication documentation by using Swagger, this seems not to be possible at all in the future. Whats also missing in Swagger is some sort of declaring private and public functions in the API which then will be published or not (but I think this could be achieved by using some sort of taffy:access meta data kind of thing).

[Marco Betschart]

As seen at Klout (http://developer.klout.com/iodocs) I/O Docs will also run in the browser and at the first sight the specification seems more robust to me than the Swagger one - on the other hand, Swagger is just fancier. Just a few mins ago, I've contacted the guys over at Wordnik and Mashery to get help on my questions. So afterwards I could definately say which of those two is the way to go for Taffy.