From this question I have seen that
Swagger and Slate serve two different purposes. Swagger is an attempt at a standardized way of describing a RESTful API.
Slate, on the other hand is a pretty theme for writing nice API docs.
It further states that
The two are not mutually exclusive
Ideally, one should generate your slate documentation from your Swagger API description
I am a bit confused. Why would I need slate when I already have Swagger UI like so.
What more do I need to ‘document’ ? I am genuinely asking because as I said I am a bit confused by their uses.
There are a few things that are worth mentioning when creating documentation for a new API.
Swagger provides a really nice graphical interface for exploring the endpoints of an API, but there are still other things that should be included in your documentation, including (but not limited to):
Authentication methods (OAuth/JWT, Basic Auth, Cookie/Session, Apikey/token)
Date formats for date output + timezone
Filtering/pagination/selecting/sorting settings for the API
Which environments exists (usually test, pre-production and production) including their differences.
Error handling including error codes, exception types and logging
Potential rate limits for your API
Terms and conditions for using your API
Most generic CoffeeScript/Backbone.js examples use attribute names like someFlag, however Rails prefers/requires some_flag.
Is anyone aware of discussion on the topic or a style guide that takes this into consideration?
I follow the convention of the server technology for my Backbone models.
For example, in my Rails applications, I set attributes using underscore names like some_value, and in my .NET applications I set attributes using capitalized names like SomeValue.
This makes it easier to integrate everything on the back-end. It's a minor inconvenience to remember to do this in the client side code, but once I'm deep in to a project, it becomes habit for that project.
The ease of the back-end integration is well worth the minor effort to use the convention that the server wants, in my opinion.
"There are only two hard things in Computer Science: cache invalidation and naming things."
-- Phil Karlton
http://martinfowler.com/bliki/TwoHardThings.html
We are building a small web application in Rails that will allow clients to interact via an HTTP POST API; a typical client being another app such as an HTML form or mobile app.
We are at the point of deciding on the API field names i.e. the POST paramater names. We are wondering if there is a particular naming convention we should go with? E.g. snake_case, camelCase etc.
Some examples:
OPTION 1
employee.address.line_1=value
OPTION 2
employee_address_line_1=value
OPTION 3
employeeAddressLine1=value
We understand that all three options are technically permissible in HTTP POST, but are there any technical pitfalls we could avoid by using one over the other? For example, should we avoid using dots "." in the field names due to the ubiquitous use of 'dot notation' within programming languages?
Any advice would be greatly appreciated.
It ultimately comes down to what you and your developers are most comfortable with. I personally use camelCase for all my variables, HTTP_POST or programming. I would stick with camelCase or snake_case, camelCase though is most popular.
Dot Notation is one of the worst forms for a naming convention, and you stated why. If you happen to use any language on the form that uses dot notation for functions or other object related tasks you can run into problems. EX: javascript - not a good example but most functions are dot notated.
Want to build a web app using SOLR as the only backend. Most of the data will be stored in SOLR via offline jobs although there is some need for CRUD.
Looking at popular web frameworks today like Rails, Django, web2py etc. despite NoSQL the sweet spot for productivity still seems to be around active record implementations sitting on top of a RDBMS.
What's the best framework, in terms of productivity, for building web apps with SOLR as the backend?
All three of the above answers are great recommendations for development frameworks. I would flip around your question and ask "Which is best web app framework for me", not "which is best with Solr" and make a decision based on your skills, the community that you have around you, and other soft factors. Especially if you are completely agnostic on which way to go.
If you have friends who love Grails and can help you get started, then Grails might be the way to go. Have a Python group that meets regularly? Then Django has a lot to offer. I personally love Rails, and so I would recommend rails. But that is only a recommendation of "What I like" versus "what is best".
The wonderful thing about Solr is how agnostic it is to the front end. It plays nice in so many environments!
The web2py Database Abstraction layer does not support SOLR at this time which means you cannot use the DAL syntax for accessing SOLR and you cannot use automatically generated forms from a SOLR DB schema. Yet you can generate forms using SQLFORM.factory as-if you had a normal relational database and perform the insert/update/select/update into SOLR manually. web2py includes libraries for parsing/writing both JSON and XMl so it will be easy to implement SOLR APIs in few lines of code. If you bring this up on the web2py mailing list we can help with some examples.
EDIT (copied from the answer on the web2py mailing list):
Normally in web2py you define a model
db.define_table('message',Field('body'))
and then web2py generates and processes forms for you:
form=SQLFORM(db.message)
if form.accepts(request.vars):
do_something
In your case you would not use define_table because web2py DAL does
not support SOLR and you cannot generate forms from the schema but you
can install this: http://code.google.com/p/solrpy/
and you can do
#in model
import solr
s = solr.SolrConnection('http://example.org:8083/solr')
#in controller
form=SQLFORM.factory(Field('body'))
if form.accepts(request.vars):
s.add(mody=request.vars.body)
s.commit()
do_something
So the difference is SQLFORM.factory instead of SQLFORM and the extra
line after accepts. That is it.
I would use Sunspot 1.2 and Rails 3.
Sunspot is commonly used as an ActiveRecord extension, but is also designed to be ORM-agnostic. Rails 3 has decoupled ActiveRecord from the framework, making it easy to go entirely ORM-free.
http://outoftime.github.com/sunspot/
By the way , SphinxSearch is a lot faster than solr/lucence and many unique features. Also search accuracy is a lot better comparing from my experience and independent benchmarks.
it have native, very easy python api and it integrates well with web2py.
but it needs a RDBMS tho . I am using it , web2py + sphinxsearch , building an office files search engine.
You can give a try too.
www.sphinxsearch.com
I'm currently working with Groovy and Grails. While Groovy is pretty straight-forward since it's basically Java, I can't say I grok Grails. I read that Groovy is to Grails as Ruby is to Ruby on Rails, but what does that mean?
To address your confusion with the metaphor (though it has been answered in other words under your question):
Groovy is to Grails as Ruby is to Ruby on Rails, but what does that mean?
Grails was a web framework built on/with the Groovy programming language to do the same thing for Groovy that Rails (a web framework for Ruby) does for Ruby.
What does it mean to be "on rails"?
The answer to this comes down to the essence of these web frameworks.
These web frameworks (Grails & Rails) are built on the premise of "convention over configuration", which means that using common conventions to develop web applications can lead to higher productivity and more maintainable applications (this is a gross generalization). And by defining a convention and sticking to that you will find that your applications are easy to generate and quick to get up and running.
This is what it means to me to be "on rails", just like a train. When a new train route is developed there is no worry about reinventing the way the train will get from one place to another, it's been solved by a single convention for decades: rails. Just as the tracks on a train route constrain its path from two locations, convention-based web frameworks use conventions to the flexibility of application developers so that they can concentrate on what the essential business problem of their application.
One key benefit of a convention for a web framework is that the web framework can now make assumptions on how certain layers of the application hook together. In Rails, one can usually assume that if one's database table has a plural name, the ActiveRecord class mapped to that table will have the corresponding singular name. Consequently, Rails code generators can consume the data-mapping information to generate data access code such as dynamic finders, migrations, lazy-loaded association traversals, etc. This data access code in a configuration-based framework is laborious to code by hand.
Several people have mentioned the technicalities of what makes Rails/Grails what they are. Several people have also mentioned "convention over configuration" as being the "rails" in Rails/Grails. This is getting closer to the truth. But this is just one characteristic of the broader philisophy of Rails, which is the concept of opinionated software.
Opinionated software can't be described in only technical terms; it's a philosophy; an ethos; an attitude. Like it or hate it, that is what's at the heart of Rails.
Here's an exceprt from a 2005 interview with David Heinemeier Hansson, creator of Rails:
Rails is opinionated software. It eschews placing the old ideals of software in a primary position. One of those ideals is flexibility—the notion that we should try to accommodate as many approaches as possible, that we shouldn't pass judgement on one form of development over another. Well, Rails does, and I believe that's why it works.
With Rails, you trade flexibility at the infrastructure level to gain flexibility at the application level. If you are happy to work along the golden path that I've embedded in Rails, you gain an immense reward in terms of productivity that allows you to do more, sooner, and better at the application level.
There is also a later interview that further explores the subject.
So being 'on rails' is a metaphor for being 'opinionated', which is why it is named as it is. That and the fact that "Ruby on Rails" is alliteratve, which any journalist or writer will tell you, is a sure-fire way of hooking people's attention.
I think a framework that strives to be "rails-like" refers to several things:
model-level: an AR-patterned ORM (rather than datamapper), migrations or some automated schema and model-layer management, handling foreign keys in the application (not in database schema, and also not using stored procedures or pure DBMS logic)
TDD encouraged: automatically generated skeletons for unit-tests,
naming conventions connecting database table names and model names, controller and view actions and HTML templates
streamlined route recognition and route generation scheme
emphasis on REST architecture
integration with ajax libs: RJS, prototype and scriptaculous
Rails is a framework for developing web applications with a database back-end. I think the name originally was a play on words. A train can take you somewhere really fast, but only where the rails go.
Being on rails means you can't control where you are going. It means, you can only go where the rails have been laid. Any attempt to go where the people who laid the rails didn't anticipate you to go will lead to frustration.
It's an automotive expression. When a car handles exceptionally well, it's said to "corner like driving on rails" (i.e. it gives you excellent control).
I don't know if that's where the rails people got that name, but that's how I interpreted it.
Really short and simple answer: Convention over Configuration.
As said above, Rails and Grails provide conventions for web application development -- naming your pieces a certain way and putting them in the right places get your application working by default with no extra configuration. When you want to deviate from the convention, you can configure your way there.
I disagree with the other comments of "on rails is a philosophy about convention over configuration" and so on.
While rails does adhere to those philosophies, "Ruby on Rails" is the name of a web framework. Nothing more, nothing less. It's not referring to any specific "on-railsness" about it, it's just a brand name in the same way that McDonald's is a brand name.
If someone else writes another framework and calls it "Python on Rails" then there'll be another brand name. If not, "XYZ on rails" just means people are being confused.
Ruby and Groovy are languages.
Ruby on Rails is a ground-breaking webapp framework. See excellent answers on opinionated software above.
As a matter of history, a working title for a Groovy webapp framework was Groovy on Rails. However the RoR community objected. The team chose Grails instead.
It's a metaphor, and I'm almost said that needs explaining. Anyway, it's an extremely good metaphor for what Ruby on Rails does. It makes it extremely easy to do (go to) the common stuff, i. e. testing, validation, deployment, MVC.