***************************************************************************
@constructs Endpoint
@description The Endpoint class is a core abstraction in carbond which models
an API as a tree of Endpoint instances, each of which is responsible
for defining how to handle a given request to a particular URI
@memberof carbond
function() {

    // -----------------------------
    // Computed read-only properties
    // -----------------------------

    /***************************************************************************
     * @property {string} path -- The URI path that routes to this endpoint. This
     *                            is built during service initialization and will
     *                            overwrite any value specified on instantiation.
     * @readonly
     */
    this.path = '' // Can be URI pattern (e.g.: "widgets/:id")

    /***************************************************************************
     * @property {carbond.Endpoint} parent -- The parent endpoint for this
     *                                        endpoint in the endpoint tree
     * @readonly
     */
    this.parent = null

    /***************************************************************************
     * @property {carbond.Service} service
     * @description The root service object managing the endpoint tree. Getting
     *              a reference to this object is sometimes necessary or just
     *              convenient (i.e., HTTP error classes can be accessed via
     *              {@link prop:carbond.Service.errors}).
     * @deprecated Use {@link func:carbond.Endpoint.getService} instead
     * @readonly
     */
    this.service = null

    // -----------------------
    // Configurable properties
    // -----------------------

    /****************************************************************************
     * @property {string} [description] -- A brief description of what this endpoint
     *                                     does. This will be displayed in any
     *                                     generated documentation.
     */
    this.description = undefined

    /***************************************************************************
     * @property {Object.<string, carbond.OperationParameter>} parameters
     * @description Operation parameter definitions that apply to all operations
     *              supported by this endpoint. Note, these will be merged with
     *              any parameter definitions on the operations themselves and
     *              their parsed values will be passed to the handler via
     *              ``req.parameters[<parameter name>]``.
     */
    this.parameters = {} // Endpoint-wide parameter definitions that apply to
                         // all operations

    /***************************************************************************
     * @property {carbond.security.Acl} acl -- The access control list for this endpoint
     * @todo implement/document
     * @ignore
     */
    this.acl = null // XXX add to docs

    /***************************************************************************
     * @property {xxx} dataAcl -- xxx
     * @todo implement/document
     * @ignore
     */
    this.dataAcl = null

    /***************************************************************************
     * @property {boolean} [sanitizesOutput=false] -- xxx
     * @todo implement/document
     * @ignore
     */
    this.sanitizesOutput = false

    /***************************************************************************
     * @property {string} [sanitizeMode=strict] sanitizeMode -- xxx
     * @todo implement/document
     * @ignore
     */
    this.sanitizeMode = 'strict' // 'strict' or 'filter' (XXX add to docs)

    /***************************************************************************
     * @property {Array.<string>?} allowUnauthenticated
     * @description Skip authentication for the HTTP methods listed on this
     *              endpoint
     */
    this.allowUnauthenticated = null // can be [] of methods

    /***************************************************************************
     * @property {boolean} [validateOutput=true]
     * @description Controls whether or not response bodies are validated using
     *              the response {@link carbond.OperationResponse.schema} corresponding
     *              to the current response code
     */
    this.validateOutput = true

    /***************************************************************************
     * @property {Object.<string, carbond.Endpoint>} endpoints
     * @description The endpoints that sit below this endpoint in the tree. URL
     *              paths to each endpoint are built during a depth first traversal
     *              of the tree on initialization using the property names defined
     *              on this Object.
     */
    this.endpoints = {}

    /***************************************************************************
     * @property {boolean} [noDocument=false]
     * @description Controls whether documentation for this endpoint is included
     *              in generated static documentation
     */
    this.noDocument = false

    /***************************************************************************
     * @property {carbond.limiter.Limiter} [limiter=undefined]
     * @description The limiter instance governing request rate limiting for the
     *              endpoint
     * @ignore
     */
    this.limiter = undefined

  }