Introduction
============

This section gives a brief introduction to what Findig is, its
design philosophy, and what to expect when using it.


What Findig is
--------------

Findig is a micro-framework for building HTTP applications. It's perhaps
comparable to Flask_ and Bottle_ in terms of size and ease of use.
Continuing in their tradition, it makes it incredibly easy to set up
a WSGI application, and avoids forcing specific choices on you
(such as a database layer or templating engine). However, Findig is
geared specifically toward building RESTful web applications, so much so
that serving HTML for web browsers with Findig would be incredibly 
counter-intuitive.

Where traditional frameworks typically describe web applications in
terms of views (or pages) and routes, Findig applications are described 
in terms of resources and CRUD actions, and the actual generation of
views is done behind the scenes. Here's an example of what an application
that serves a simple JSON API looks like in Findig::

    from findig.json import App
    from dbstack.users import get, save, delete
    
    app = JSONApp()

    @app.route("/users/<int:id>")
    def user(id):
        user = get(id)
        return user.as_dict()

    @user.model("write")
    def user(data, id):
        save(id, data)
        return get(id).as_dict()

    @user.model("delete")
    def user(id):
        delete(id)

    # app is a WSGI callable that can be run by your
    # WSGI server of choice

This code will accept and respond to application/json
``GET|PUT|DELETE`` requests sent to ``/users/:id`` on the server, 
as long as ``id`` looks like an integer. Notice how rather than 
describing the resource in terms of how it looks (i.e., a view), the 
resource is described in terms of how to read, write and delete its data.
It's implied that Findig will use this data to organize the
views and construct the responses. Behind the scenes the 
:class:`findig.json.App` converts the resource data into a JSON formatted
response.

A word on customization
-----------------------

As seen above, Findig lets you describe how to manipulate resource data
and then runs along and does everything else to handle requests 
(including parsing input and formatting output). If that sounds a little
heavy on the fascism, don't despair; it's actually really customizable. 

Input parsing, output formatting and error handling can be globally or 
selectively overridden in all Findig applications. For example, if we 
wanted to also output to XML based on an accept header, 
we could add the following code::

	@user.formatter.register("application/xml")
	def format_xml_response(user_dict):
		# This registers an xml formatter for the user resource
		xml = generate_user_xml_by_some_means(user_dict)
		return xml

.. todo:: Provide links to parts of documentation explaining extending
          parsing, formatting and error handling.

In addition, a lot of Findig's internals are based on abstract classes,
allowing you to plug in custom components that do things just the way you
want them done (let's hope it never comes to that, though).

When to use (and not to use) Findig
-----------------------------------

.. note:: Findig is plain and simple pre-release software. This section
          right now is largely irrelevant for production applications:
          *you simply don't*.

Findig is an API framework that's intended for building APIs, and it aims
to be great at doing only that. As a result, support for applications that
talk to traditional web browsers is virtually non-existent. Instead, use
Findig if you want to build a backend API that powers your web apps and/or
mobile applications.

.. note:: Findig can be used to back angularjs_ apps.

.. _flask: http://flask.pocoo.org/
.. _bottle: http://bottlepy.org/
.. _angularjs: http://https://angularjs.org/