2.0 and the future

[Jack Chu]

I'm going to continue the discussion started in GitHub (https://github.com/mattetti/wd-sinatra/issues/34) here. I figured this would be better than a GH issue to discuss and explore where to take WD.

I've been trying to clean up things for the wd_sinatra 2.0 release and I was actually about to release it tonight, but then I looked at the core team issue and thought the 2.0 should be the start of where we want to take things. Git master already breaks a good deal of 1.x wd_sinatra apps, but I figured we should figure out what 2.0 is before we release it, so the next release doesn't just break all compatibility again.

Documentation

I also agree that documentation should be moved into WeaselDiesel. I was thinking that WD alone should allow you to define specs for an API prototype or existing API and generate html/markup documentation for those specs. So Matt could make use of WD to generate documentation for his Golang based API. I was thinking that we could have themeable web documentation similar to Github's API docs (http://developer.github.com/v3), navigate by resources, and then by endpoints per resource. I think an SPA might be good enough here.

I think Markdown support in doc strings would be better than raw html. This would make it easier to output documentation as markdown.

As for how to generate docs, I'm thinking a middleman app inside WD. The ruby files where the services are defined get loaded in the middleman config.rb and then rendered via rake task or middleman CLI.

Meta API

There are some tickets that have to deal with API meta information, like about what the API does overall, how it handles pagination, rate limiting, authentication, errors (what the response looks like), etc. Stuff that doesn't belong defined per service endpoint. I do think we need some way to define these things.

Success/Error Codes

We should address how to specify codes via the WD DSL. I think the proposals I saw only allow 1 code per service/response, but it's definitely possible to return more than 1 error code per endpoint.

Versioning

We have differing views on how versioning should be implemented, and that's fine, but the WD DSL should have a way of specifying version. When doc generation happens we can then split endpoints up by version. If you're working against one version of the API, you likely will not need to see endpoint documentation for an older version.

[wd_sinatra] Authentication

I think most APIs need to deal with authentication. It would be nice if we could provide a proof of concept or gem module that supplied oAuth support. I implemented this in a sinatra API I worked on earlier this year, so this is something I thought I might be able to support. However, I know that auth is going to be tied to data persistence, and wd_sinatra allows you to use any ORM, so that might be a hurdle to be able to support any ORM.

[Matt Aimonetti]

Sounds good, just a few points:

*  If you're working against one version of the API, you likely will not need to see endpoint documentation for an older version  <-- well it works great when your APIs are namespaced, since you go to the endpoint's version you want to use :)

* auth: wd_sinatra has a bunch of hooks for that. I agree it would be nice to have a few basic implementations for oauth and other auths. The data persistence layer problem can be solved by providing a delegate/hook/proc to handle the lookups. Usually for authentication solutions, the DB access is very minimum since you want the auth process to be fast. In theory, having a way to point to a class/module/wtvr implementing a certain interface might make things very easy.

--
https://github.com/mattetti/wd-sinatra
https://github.com/mattetti/Weasel-Diesel
---
You received this message because you are subscribed to the Google Groups "WeaselDiesel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to weaseldiesel...@googlegroups.com.
Visit this group at http://groups.google.com/group/weaseldiesel.
For more options, visit https://groups.google.com/groups/opt_out.

[Raul Murciano]

Documentation: I like the idea of generating Markdown and using it to generate HTML as well. I don't see the need to add Middleman (and its dependencies) to a project that seems to be very language agnostic – what about using a plain Markdown processor (e.g: redcarpet) + a rake task?

Success/Error codes: I wrote a proposal time ago, you may find it useful as a starting point.

I fully agree with all the other points you mention.

--

Raul Murciano
http://www.raulmurciano.com

[Jack Chu]

I started a PR in an attempt to move the current doc generator in wd_sinatra into WD as a Thor CLI.

https://github.com/mattetti/Weasel-Diesel/pull/30

Let me know what you think.

BTW, I was thinking middleman, so we could make it easier for users to deploy, create themes, deal with asset minification/concatenation/digesting, etc.

[Matt Aimonetti]

In not a big fan to adding more dependencies if we can avoid them. What does middleman brings to the end user?

[Jack Chu]

I noted in my previous reply. It would buy the user easier deployment, it might make theming easier if that's something we're going to support, assuming themes need to bring in images and javascript, it'll get us asset management/concat/minification/digesting. I'm not 100% sure it's a good fit yet. It largely depends on how we let the end user customize the API template, if we do at all. Maybe for now it's similar to rdoc. You can't customize it, you just generate it and throw it up somewhere as is. 

I think the current PR to move documentation generation into WD is a good first step. In the future, it might be useful for users to be able to customize the theme so they can brand their API docs and then just sync them somewhere. Right now you could generate docs and then style it anyway you like, but when you regenerate it you would have to restyle it all over again. But, short term, allowing people to easily generate any API docs is probably a win. I know in my previous job if I had a tool that could just do API doc generation, I would have totally used it.

[Matt Aimonetti]

good points

On Mon, Aug 26, 2013 at 10:09 PM, Jack Chu <kam...@gmail.com> wrote:

I noted in my previous reply. It would buy the user easier deployment, it might make theming easier if that's something we're going to support, assuming themes need to bring in images and javascript, it'll get us asset management/concat/minification/digesting. I'm not 100% sure it's a good fit yet. It largely depends on how we let the end user customize the API template, if we do at all. Maybe for now it's similar to rdoc. You can't customize it, you just generate it and throw it up somewhere as is. 

I think the current PR to move documentation generation into WD is a good first step. In the future, it might be useful for users to be able to customize the theme so they can brand their API docs and then just sync them somewhere. Right now you could generate docs and then style it anyway you like, but when you regenerate it you would have to restyle it all over again. But, short term, allowing people to easily generate any API docs is probably a win. I know in my previous job if I had a tool that could just do API doc generation, I would have totally used it.

--