src/config/http-handlers.rst

.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. highlight:: ini

======================
HTTP Resource Handlers
======================

.. _config/httpd_global_handlers:

Global HTTP Handlers
====================

.. config:section:: httpd_global_handlers :: Global HTTP Handlers

  These HTTP resources are provided for CouchDB server root level.

  .. config:option:: /

    ::

      [httpd_global_handlers]
      / = {couch_httpd_misc_handlers, handle_welcome_req, <<"Welcome">>}



  .. config:option:: favicon.ico

    The favicon handler looks for `favicon.ico` file within specified directory::

      [httpd_global_handlers]
      favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}



  .. config:option:: _active_tasks

    ::

      [httpd_global_handlers]
      _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}



  .. config:option:: _all_dbs

    Provides a list of all server's databases::

      [httpd_global_handlers]
      _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}

    .. note::

       Sometimes you don't want to disclose database names for everyone, but
       you also don't like/want/able to setup any proxies in front of CouchDB.
       Removing this handler disables ``_all_dbs`` resource and there will be
       no way to get list of available databases.

       The same also is true for other resource handlers.



  .. config:option:: _config

    Provides resource to work with CouchDB config :ref:`remotely <api/config>`.
    Any config changes that was made via HTTP API are applied automatically on
    fly and doesn't requires server instance to be restarted::

      [httpd_global_handlers]
      _config = {couch_httpd_misc_handlers, handle_config_req}



  .. config:option:: _log

    ::

      [httpd_global_handlers]
      _log = {couch_httpd_misc_handlers, handle_log_req}



    .. config:option:: _oauth

    ::

      [httpd_global_handlers]
      _oauth = {couch_httpd_oauth, handle_oauth_req}



  .. config:option:: _replicate

    Provides an API to run :ref:`temporary replications <api/server/replicate>`::

      [httpd_global_handlers]
      _replicate = {couch_replicator_httpd, handle_req}



  .. config:option:: _restart

    ::

      [httpd_global_handlers]
      _restart = {couch_httpd_misc_handlers, handle_restart_req}



  .. config:option:: _session

    Provides a resource with information about the current user's session::

      [httpd_global_handlers]
      _session = {couch_httpd_auth, handle_session_req}


  .. config:option:: _stats

    ::

      [httpd_global_handlers]
      _stats = {couch_httpd_stats_handlers, handle_stats_req}


  .. config:option:: _utils

    The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
    page::

      [httpd_global_handlers]
      _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}

    In similar way, you may setup custom handler to let CouchDB serve any static
    files.


  .. config:option:: _uuids

    Provides a resource to get UUIDs generated by CouchDB::

      [httpd_global_handlers]
      _uuids = {couch_httpd_misc_handlers, handle_uuids_req}

    This is useful when your client environment isn't capable of providing truly
    random IDs (web browsers e.g.).


.. _config/httpd_db_handlers:

Database HTTP Handlers
======================

.. config:section:: httpd_db_handlers :: Database HTTP Handlers

  These HTTP resources are available on every CouchDB database.


  .. config:option:: _all_docs

    ::

      [httpd_db_handlers]
      _all_docs = {couch_mrview_http, handle_all_docs_req}



  .. config:option:: _changes

    ::

      [httpd_db_handlers]
      _changes = {couch_httpd_db, handle_changes_req}



  .. config:option:: _compact

    ::

      [httpd_db_handlers]
      _compact = {couch_httpd_db, handle_compact_req}



  .. config:option:: _design

    ::

      [httpd_db_handlers]
      _design = {couch_httpd_db, handle_design_req}



  .. config:option:: _temp_view

    ::

      [httpd_db_handlers]
      _temp_view = {couch_mrview_http, handle_temp_view_req}



  .. config:option:: _view_cleanup

    ::

      [httpd_db_handlers]
      _view_cleanup = {couch_mrview_http, handle_cleanup_req}


.. _config/httpd_design_handlers:

Design Documents HTTP Handlers
==============================

.. config:section:: httpd_design_handlers :: Design Documents HTTP Handlers

These HTTP resources are provided for design documents.


  .. config:option:: _compact

    ::

      [httpd_design_handlers]
      _compact = {couch_mrview_http, handle_compact_req}



  .. config:option:: _info

    ::

      [httpd_design_handlers]
      _info = {couch_mrview_http, handle_info_req}



  .. config:option:: _list

    ::

      [httpd_design_handlers]
      _list = {couch_mrview_show, handle_view_list_req}



  .. config:option:: _rewrite

    ::

      [httpd_design_handlers]
      _rewrite = {couch_httpd_rewrite, handle_rewrite_req}



  .. config:option:: _show

    ::

      [httpd_design_handlers]
      _show = {couch_mrview_show, handle_doc_show_req}



  .. config:option:: _update

    ::

      [httpd_design_handlers]
      _update = {couch_mrview_show, handle_doc_update_req}



  .. config:option:: _view

    ::

      [httpd_design_handlers]
      _view = {couch_mrview_http, handle_view_req}