Dashboard UI Overhaul

[atuttle]

• Something that doesn't look like the hamburglar shat it out after eating a bunch of McDonalds and hot sauce would be nice. How about Swagger?
• Maintain dashboard state through a framework reload (Dashboard API reload should maintain UI state #63)
• Show response times from mock/test requests (Dashboard should show response time #64)
• Unless anyone objects, we can probably get rid of the PDF documentation stuff. If we go with Swagger, it looks like it is a nice clean inline documentation.

[marbetschar]

Already thought about better testing tools in the dashboard and stumpled across swagger too. Additional possibilities such as using OAuth or any other security type of thing would be great in the dashboard. We are running now an OAuth 1.0 powered API with taffy and therefore the current dashboard is quite useless for testing the endpoints :(

So +1 from my end for improving the dashboard. If I could provide any help on this one, please let me know!

[atuttle]

If you want to try your hand at a new dashboard with Swagger, be my guest! Just keep in mind that not everyone will be using OAuth. It's fine if it's supported, just don't want it to be a requirement.

In theory you should just need to rewrite dashboard.cfm.

[marbetschar]

As mentioned before we've just started our own business and therefore we are terrible busy.

BUT: I really love what you've done with Taffy and would appreciate it if I could do more for the project as enhancing the dashboard. For sure this have to be done on a generic way, regardless of any static security implementations such as OAuth etc.

As I'm currently not aware of your plans, ideas and targets for Taffy we may set up a Skype call to discuss the details of how we may go further best? So in the end Taffy gets the most out of the time spent on it.

I'm not aware of your working hours and the time shift right now - my time zone is +1 GMT. So we may have a call on tuesday at 8pm +1GMT? I think this is somewhen during the day in your time zone?

Am 21.09.2012 um 15:09 schrieb Adam Tuttle notifications@github.com:

If you want to try your hand at a new dashboard with Swagger, be my guest! Just keep in mind that not everyone will be using OAuth. It's fine if it's supported, just don't want it to be a requirement.

In theory you should just need to rewrite dashboard.cfm.

—
Reply to this email directly or view it on GitHub.

[atuttle]

If I'm doing the conversion right (you're the same TZ as London?), that will be 3pm here. That's fine. I'm on Skype now, you can call whenever works best for you. :)

[marbetschar]

To getting things further:
I've just comparing Swagger to I/O Docs right now and can't see any major difference. What are the benefits of Swagger over I/O Docs and vice versa?

Just to make sure we had a discussion about it and go on with the best way.

[atuttle]

Never heard of I/O Docs, and as long as it looks good and works well (and doesn't add any unnecessary bloat to the project) I'm cool with either.

[marbetschar]

As for now I don't see any big difference between Swagger and I/O Docs I give Swagger a try since it looks nicer. Please tell me on which branch I should start implementing the new dashboard.

[atuttle]

Create a new branch based on 1.2-dev called ER84
On Oct 1, 2012 7:17 PM, "marbetschar" notifications@github.com wrote:

As for now I don't see any big difference between Swagger and I/O Docs I
give Swagger a try since it looks nicer. Please tell me on which branch I
should start implementing the new dashboard.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/84#issuecomment-9053740.

[marbetschar]

Just got the time to create a first example on how to implement the swagger specification into taffy. Looking forward to your feedback on my implementation:
https://github.com/marbetschar/Taffy/tree/er84

A short description about how the current implementation works:

1. I've added a parent beanFactory which loads all global resources stored in taffy.core.resources
2. the taffy.core.resources.swagger is responsible for creating the swagger compliant api documentation (it is added as /swagger)
3. requests to an api resource containing the "swagger=true" query string param are routed to the global /swagger resource

As of 3) here's a little example of what happens. Let's assume you have a REST resource called /cats in your API. If you are calling /cats?swagger=true then the request will be routed to /swagger?resource=/cats and the taffy.core.resources.swagger is responding with the requested documentation of the /cats endpoint.

As for now I'm not happy with the current implementation of this yet, since I've hardcoded the following lines into taffy.core.api.

<cfif requestObj.uri NEQ '/swagger' AND findNoCase('swagger=true',requestObj.queryString)>
    <cfset requestObj.queryString = replaceNoCase(requestObj.queryString,'swagger=true','resource=#requestObj.uri#') />
    <cfset requestObj.uri = '/swagger' />
</cfif>

This seems wrong to me, since there may be additional things which would benefit of a routing. Maybe a global route handling should be implemented to solve this issue?

[atuttle]

Is there a reason you didn't just replace the current dashboard? Why create a new URL for it?

[marbetschar]

I've not added a bew URL, I've just added a Swagger endpoint as the Swagger specification relies on a self describing API and therefore does some API Requests to get the JSON Documentation from it.

That's why I have to add a /swagger endpoint and a specific param for distuingish between Swagger and regular API calls.

Am 08.10.2012 um 20:24 schrieb Adam Tuttle notifications@github.com:

Is there a reason you didn't just replace the current dashboard? Why create a new URL for it?

—
Reply to this email directly or view it on GitHub.

[atuttle]

Ah, ok. Then how about making it /dashboard so that it's more technology agnostic?

[marbetschar]

As of this, I think the main purpose of this endpoint is to provide documentation about the underlying API and its resources. That's why Swagger talks about a /resources endpoint in their specification - and I think this is a good idea.

As for now, I don't know exactly how I/O Docs works and on which API endpoints it does depend on (if any). So we may decide first which of these two is the way to go and talk about the implementation issues afterwards?

[atuttle]

Have you made any progress on this? I'd like to get 1.2 out by the end of the year, so for now I'm pushing it back to a future release. That could very well be 1.2+1 (1.3? 2.0?) if it'll be done in time... Or if you're nearly done, share what you've got and maybe we can get it in 1.2...

Check out the Releases page of the wiki to see all of the stuff that's ready to roll out at any time. :)

[marbetschar]

Glad to see you have already pushed 1.2 to the world. As posted on your blog I wasn't able to digg deeper into this issue till now.

I've already made progress with Swagger and got some call with Mashery about I/O Docs. Currently I feel like I/O Docs is the way to go as it is more feature complete than swagger.

I'll put some more time into the dashboard in the following weeks, so we may release it hopefully in the next version of Taffy.

[atuttle]

Started working on a concept mock-up today. What do you think? (click through for full-size)

[atuttle]

One thing that's missing from this concept is additional response headers. Anyone want to suggest a place to list them?

[atuttle]

I could do this, with the potential down-side that if many headers are returned, the list could get long: