Home

Conventions

In the application core (core.js), resources will generally follow a noun-verb convention. Resource paths shall traverse nouns in a descending level of granularity with any verb (optional), indicative of a processing action, to be at the end of the resource path. A resource path need not have a verb but, if it does, it should only contain one. Consider the following paths:

noun-only:
/vector/:schema/:table/:geom
noun-verb:
/vector/:schema/:table/:geom/:operation

The noun-only is currently represented in the core as the resource path to fetch the GeoJSON representation of a table. An example path would be:

/vector/public/parcels/features

Note that the path starts with the very general (vector) and proceeds to the specific (features). Now consider the following example that ends in a verb:

/vector/public/parcels/features/buffer

In this case, "intersect" is the verb describing an operation. This should terminate the resource path. Depending upon the HTTP verb used to call upon the resource, it would be appropriate to append any query string parameters necessary to correctly call the operation. So the following would be considered in accordance with convention:

/vector/public/parcels/features/buffer?distance=5&units=meters

To buffer a specific feature, the feature identifier should precede the 'buffer' verb in the resource path:

/vector/public/parcels/features/7/buffer?distance=5&units=meters

The core application will generally place all resources under 'vector' to denote resource or operations on vector layers. (Raster support may be added in the future.) It is recommended that custom extensions use a custom resource root to avoid potential collisions. For example, an extension that provides custom interface for data related to Leonardtown, Maryland may choose to start all resource paths with "leonardtown" like so:

/leonardtown/buildings/commercial

The application core will apply these conventions to the greatest extent possible. While it is not necessary for custom extensions to follow these conventions, it is recommended for consistency.