Introduction¶

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 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

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¶

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.