The wq URL Structure

wq version: 0.7.8 1.0 1.1
Docs > API Conventions

The wq URL Structure

The wq stack is designed to support building offline-capable websites / web apps with application screens that can be rendered on the client or on the server depending on what will provide the best user experience. To facilitate this design, wq defines a consistent but flexible URL structure that is shared throughout the application as well as its REST API. This structure is defined here independently of the implementations in wq.app and wq.db, with the idea that either library can be exchanged for another architecture as long as the URL structure is maintained.

Basic URL Structure

Every URL is assumed to be relative to a shared base URL. For simplicity, the base URL is assumed in this document to be the website root URL (/), but this can be customized on a per-application basis. The base URL should be capable of serving the "home" or "index" page of the application. For all other pages, the basic structure is /[url][.format], where url is any of the URL types described below and format is one of the following.

Format Specification

With few exceptions, every URL should be capable of being rendered by the server (i.e. the REST service) in both HTML and JSON formats. Among other things, this makes it easy to debug the underlying data source(s) behind an application screen. The desired format can be specified by the client via HTTP Accepts: headers or, more often, by appending a short format string to the URL (in the style of a file extension).

Below are the format types supported by wq.db. Only the HTML and JSON formats are strictly required for wq compatibility.

format extension content type purpose
HTML .html text/html (Default) This is the format used for application screens shown to the user. This format is used when no format is specified (i.e. the URL does not end in an file extension). The client application (i.e. wq.app) should typically be able to render extension-free URLs locally using data requested via the JSON version.
JSON .json application/json This is the basic format used by clients to retrieve data collections from the server.
GeoJSON .geojson application/vnd.geo+json (Optional) This format can be used to load and display data collections that incorporate geographic coordinates, for example in wq/map.js.

List API Structure

The most common type of URL structure in a REST API is the list, or collection. In wq.db, lists are backed by Django ORM models that correspond to a database table. The list URL is usually a lower case, plural name for the collection. Like most REST APIs, wq uses different HTTP verbs (GET, POST, and PUT) to support retrieving, creating, and updating list items, respectively. wq's REST implementation provides a couple of additional URLs to facilitate rendering HTML forms. For convenience, the default template wq uses for each URL is listed below in addition to the REST information.

verb path template purpose
GET /[list_url] [list]_list.html Retrieve all items from the list (or all items from the first page of the list, if the list is paginated).
GET /[list_url]?page=[num] [list]_list.html Retrieve items from page num in a paginated list.
POST /[list_url] [list]_detail.html Add a new member to the list. The properties of the new member should be specified in the POST data (either JSON or form data).
GET /[list_url]/new [list]_edit.html (HTML only) Display an HTML form suitable for creating a new member of the list. The form will presumably POST to the list URL above.
GET /[list_url]/[id] [list]_detail.html Retrieve a single member from the list via primary key or identifier.
PUT /[list_url]/[id] [list]_detail.html Update a single member in the list. The properties should be specified in the PUT data (either JSON or form data).
GET /[list_url]/[id]/[edit] [list]_edit.html (HTML only) Display an HTML form suitable for editing an existing member of the list. The form will presumably PUT to the detail URL above. (wq.app can handle AJAX form submissions automatically. For regular / non-AJAX form submissions, a hidden input named _method should be used to ensure the right method is set since many browsers don't support PUT as a form method.)

Optional List Extensions

wq.app and wq.db support a couple of additional URL types that improve user experience but aren't commonly implemented in REST API structures. These aren't strictly required for wq compatibility.

verb path template purpose
GET / [list]_list.html It is possible in wq to have lists directly attached to the root URL. This usually used for the most important list in the site. For example, the wq website has a Page model that is attached to the root URL so all "pages" can be accessed as e.g. /about rather than /pages/about.
GET /[id] [list]_detail.html An individual member of a list attached to the root URL (e.g. /about).
GET /[parent_list]/[id]/[child_list] [child_list]_list.html The members of child_list, filtered by a common foreign key. For example, in the wq website, /chapters/api/docs lists all of the Doc instances with a foreign key pointing to the "api" Chapter.
GET /[list]-by-[parent_list] [parent_list]_list.html A helper view for generating /[parent_list]/[id]/[list]-style links. Identical to a normal list view, but with an extra target context variable with the URL of the intended child list.

Special Pages

There are a number of additional pages that might exist in a wq-powered website and REST api.

verb path template purpose
GET /[name] [name].html Any non-list page will follow the basic convention that the URL is the same as the template name. The most common example is the login page provided by wq.db.
POST /[name] [name].html Some non-list pages (e.g. login) will allow submitting data via POST. The same URL and template are used.
GET / [name].html If the root URL is not a list URL, and it's not a static page controlled by the webserver, then it should be specified as a simple non-list page. (A common name for this page would be index).
GET /config.json n/a The auto-generated wq configuration object. This object is used to communicate the entire URL structure to the client application. This file can also be generated on the command line via ./manage.py dump_config if wq.db.rest is in your application's INSTALLED_APPS.