Create a spec

[dhutty]

If we create specification, it would make it easier to create examples in new languages/frameworks (and test them).

This could be done iteratively with several levels depending on the time/effort available:

• Broad, qualitative description of what the app should do
• Complete ReST API docs
• Test suite(s) to test functionality (unit testing would of course, be in the domain of the developer of each example stack).

[pdurbin]

This should go in a top level readme but for now here's where the idea for this repo started: http://irclog.greptilian.com/friendlyjava/2015-03-28#i_105286

All the REST stuff is something I added because I felt like it. And because I find Jersey more fun than JSF. :)

Some more discussion at http://irclog.greptilian.com/sourcefu/2015-04-06#i_107536 but let's say for now your address book should allow you to enter a name and phone number. :)

But yes there absolutely should be a spec or at least some more guidance! Thanks for opening this issue!

[aditsu]

Here's my original idea:

• have a database with a table with names and phone numbers (and probably a surrogate key)
• the application should list all the entries (optionally paged)
• you should be able to add, edit and delete an entry
• each entry has 2 fields: name and phone number
• any other features are optional

[JasonWoof]

I think you should stardardize the front-end a bit. like decide if it's all ajaxy or not

It would be hard to compare frameworks if, eg, one is pretty much only doing ajax, and another is proccessing form submissions

[aditsu]

The plan was to keep it really simple. If it's up to me, I'd say no ajax.
I don't know why anybody would use ajax for this, but then people are already coming with all kinds of crazy ideas...

[prologic]

I think we should do two thigns:

• No AJAX; but an API that could be used as such.
• Simple unstyled HTML UI with forms

[aditsu]

I don't think an API should be required. What's the point of that?
Also, why should the interface be "unstyled"? A little CSS doesn't hurt anybody.

[prologic]

Yeah I dunno really; I just don't think you're demonstrating much by not having an API and just rendering a bunch of HTML depending on the Request path :)

[aditsu]

"just rendering a bunch of HTML"?! No, it's about listing, adding, deleting and changing entries in a contact list on the server side.

[prologic]

Yeah I know :) But to me I see the two as being very different.

[dhutty]

A few separate comments:

A.
If there are substantive differences in the ways the various solutions support the use or generation of CSS, then it would be useful to include demonstration of this. I think it might be helpful to those who do backend work (only) if we could provide some boilerplate CSS to make things a little less ugly/plain, but that its use should be optional, i.e. not part of the spec/tests.

B.
There are 2 primary reasons to include a (ReST) API service as part of the spec and not "just" return HTML to be rendered:

1. People comparing frameworks often want to compare how frameworks help/hinder writing API services. It's common that for apps that are anything more than trivial, the front end will be completely separate anyway and that there will likely be more than one front end, which case demands an API service.
2. Better alignment with the basics of unix philosophy, especially the rules of {modularity,composition,simplicity}. It will be easier to read/write the code that manipulates requests/responses/data if there's no HTML in the way.

C.
If we have a (moderately) complete spec and an API service, we can have a separate project for plain/AJAX/whatever frontends that consume this service and then people can use/investigate/learn whichever parts they are interested in.

[aditsu]

prologic: I'm not sure what you're talking about.
dhutty:
A. I agree css should be optional. I'm using a static, hand-written css file with about 30 lines. It's separate from the actual code.
B./C. That goes beyond the initial goal to implement a minimal demo. So I'd make the API optional, but maybe I'm in the minority :p

[dhutty]

@aditsu
A. sure, we should include that in an implementation-independent section of the repo, preferably with a doc to explain the purpose of each css class etc.

[aditsu]

Um.. I don't think it's feasible to have a common stylesheet for all implementations, unless we standardize the html structure of every page. I'm just saying: let people use a little css if they would like to. Unstyled pages, especially with tables, can look pretty ugly.

[dhutty]

Since this project is focused on comparing/demonstrating the server-side technologies, the backend, I don't see any reason why we shouldn't standardize the html of each page. Or at least offer a default.

[aditsu]

That seems quite restrictive, and some things may be a natural fit in one framework but inconvenient in another one. For example, two frameworks could provide different default ways to list a bunch of items or to show error messages, including different css class names. Some implementations will have to do more work to customize the generated html, which they would not normally do in a real project.

[dhutty]

ok, soften it to: "offer an example"

[pdurbin]

Great discussion!

Everyone should pay attention to the summary by @aditsu at #4 (comment) because it does capture the original idea.

I would say that a database is not a requirement but some sort of server-side persistence is.

Also, as I just commented at https://github.com/pdurbin/addressbookmvc/pull/12/files#r33887453 I think we should de-emphasize anything about a RESTful API in any kind of readme describing the goals. The implementation still needs to function if you disable the RESTful API.

The emphasis of this project is a comparison of building the same simple web application using a traditional server-side approach to build the user interface.

Recently I was listening to http://ttlpodcast.com/episodes/emily-nakashima.html with @eanakashima and @rmurphey and this quote should provide some inspiration:

Emily: You know, we’re really minimalist about JS in a way that I think so many other sites right now are not. I think the tagline that I hear around the office sometimes is, “Build websites like it’s 2004,” like everything is very kind of old-school HTML page request-response standard browser navigation, so we don’t do Angular, Ember, Backbone, anything like that.

[pdurbin]

Ok, I merged the spec by @dhutty in #12 into master. Thanks! Since we have a spec now I guess I'll close this issue. Everyone should feel free to open issues or simply sent pull requests for proposed changes to the spec.