Publishing Uniform Resource Locators (URLs)

by Jon Salz and Michael Yoon on 6 July 2000

ACS Documentation : ACS Core Architecture Guide : API Publication : Publishing URLs


The Big Picture

The /user-search page is the canonical example of a "URL API", in that it behaves like a function: it accepts a defined set of inputs; it returns a defined set of outputs; you "invoke" it programmatically (by redirecting the browser to its URL).

Prior to ACS 3.3.1, the only documentation for a URL like /user-search would typically reside in comments at the top of the corresponding file on the server. The inputs expected by a URL would usually be enumerated in a call to ad_page_variables or, worse yet, in a comment somewhere in the vicinity of a call to set_the_usual_form_variables.

ACS 3.3.1 supersedes this informal combination of page header comments and ad_page_variables with the new procedure ad_page_contract, which enables us to present the definition and documentation of a URL API separately from its implementation.

How to Use ad_page_contract

The syntax for calling ad_page_contract is:
ad_page_contract doc-string arg-list 
ad_page_contract should be called at the top of every Tcl page, in place of a header comment and a call to ad_page_variables.

The arg-list argument enumerates the variables that the page expects to be included in the form data set. Like ad_page_variables, ad_page_contract sets the specified arguments as variables in the context of the Tcl page.

In addition to a name, each entry in the arg-list can have a default value, specified using the same syntax as proc: a two-element list where the first element is the argument name and the second argument is the default value.

Argument Validation

Unlike ad_page_variables (which only ensures that all expected inputs are supplied), ad_page_contract actually validates page input values. Validation rules are specified by following the argument name with a colon and then one or more of the following flags (separated by commas if more than one):

Page Documentation Strings

Like ad_proc and ad_library, ad_page_contract accepts Javadoc-inspired documentation strings, i.e., a general description of the page's function, followed optionally by a series of named attributes tagged with @ signs:

These @ tags are optional, but highly recommended. (For ACS Core Team programmers, they are mandatory.)

Examples

Here's a simple, hypothetical example of using ad_page_contract:
# /www/recipes/one.tcl
ad_page_contract {
    Presents one recipe, optionally in a printer-friendly format

    @param recipe_id the ID of the recipe to be presented
    @param printable_p printer-friendly or not?

    @author Michael Yoon (michael@ardigita.com)
    @creation-date 1 January 2001
    @cvs-id $Id$
} {
    recipe_id:integer
    printable_p:integer
} 

Here's a more sophisticated example from the forthcoming API Browser:

# /packages/acs-core/api-doc/www/package-view.tcl
ad_page_contract {
    Shows the APIs for a particular package.

    @param version_id the ID of the version whose API to view.
    @param public_p view only public APIs?
    @param kind the type of API to view. One of <code>procs_files</code>,
        <code>procs</code>, <code>content</code>, <code>types</code>, or
        <code>graphic-designer</code>.
    @param format the format for the documentation. One of <code>html</code>
        or <code>xml</code>.

    @author Jon Salz (jsalz@mit.edu)
    @creation-date 3 Jul 2000
    @cvs-id $Id$
} {
    version_id:integer
    public_p:optional
    kind
    { format "html" }
} 
By convention, ad_page_contract is preceded by a comment line containing the file's path. The comment is on the first line of the file, and the contract starts on the second.

Future Improvements

We plan to integrate ad_page_contract with the next iteration of the Document Builder API. It will then support explicit specification of what type of content (e.g., html-content-pane) the page returns, which the Request Process can use for document transformation (e.g., master template wrapping, WAP presentation) and template writers can use to determine what document properties (i.e., variables) are available for each URL.
jsalz@mit.edu