Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
branch: master
278 lines (202 sloc) 9.036 kB
.. _http-interface:
==============
HTTP Interface
==============
.. default-domain:: mongodb
.. _rest-interface:
REST Interfaces
---------------
RESTHeart (Java)
~~~~~~~~~~~~~~~~
`RESTHeart <http://www.restheart.org>`_ Java REST API server for
MongoDB, built on top of `Undertow <http://undertow.io>`_ non-blocking
HTTP server. License: GNU AFFERO GENERAL PUBLIC LICENSE Version 3.
- CRUD operations API on your data;
- Data model operations API: create databases, collections, indexes
and the data structure;
- Super easy setup, with convention over configuration approach;
- Pluggable security with User Management and ACL;
- `HAL <http://en.wikipedia.org/wiki/Hypertext_Application_Language>`_ hypermedia type;
- Super lightweight: pipeline architecture, ~6Mb footprint,
~200Mb RAM peek usage, starts in milliseconds;
- High throughput: very small overhead on MongoDB performance;
- Horizontally scalable: fully stateless architecture supporting
MongoDB replica sets and shards;
- Built on top of `Undertow <http://undertow.io>`_ non-blocking HTTP server;
- Embeds the excellent `HAL browser
<https://github.com/mikekelly/hal-browser>`_
by Mike Kelly (the author of the HAL specifications);
- Supports `Cross-Origin Resource Sharing
<http://www.w3.org/TR/cors/>`_ (CORS) so that your one-page web
application can deal with RESTHeart running on a different
domain. In other words, CORS is an evolution of `JSONP
<http://en.wikipedia.org/wiki/JSONP>`_;
- Ideal as AngularJS (or any other MVW Javascript framework) back-end.
DrowsyDromedary (Ruby)
~~~~~~~~~~~~~~~~~~~~~~
`DrowsyDromedary <https://github.com/zuk/DrowsyDromedary>`_
is a REST layer for MongoDB based on Ruby.
Crest (Node.jS)
~~~~~~~~~~~~~~~~~~~~~~
`Crest <https://github.com/cordazar/crest>`_ is a REST API Server for
MongoDB built in node.js using the
`MongoDB Node Native driver
<https://github.com/christkv/node-mongodb-native>`_.
AMID
~~~~
`AMID <https://github.com/mariano-fiorentino/amid>`_ is a REST
interface for MongoDB. Written in Node.js, supports multi-threading
and a modular architecture to perform custom search operation.
AMID also provides an optional extjs GUI for queries: `AMIDGUI
<https://github.com/mariano-fiorentino/amidGUI>`_.
Mongodb Java REST server
~~~~~~~~~~~~~~~~~~~~~~~~
`Mongodb Java REST server <https://sites.google.com/site/mongodbjavarestserver/home>`_
based on `Jetty <http://www.eclipse.org/jetty/>`_.
Kule
~~~~
`Kule <https://github.com/fatiherikli/kule>`_ is a customizable REST
interface for MongoDB based on Python.
DreamFactory
~~~~~~~~~~~~
`DreamFactory <http://www.dreamfactory.com>`_ is an open source backend
with a REST API for MongoDB. `DreamFactory on GitHub <https://github.com/dreamfactorysoftware>`_.
HTTP Interfaces
---------------
Sleepy Mongoose (Python)
~~~~~~~~~~~~~~~~~~~~~~~~
`Sleepy Mongoose <http://www.kchodorow.com/blog/2010/02/22/sleepy-mongoose-a-mongodb-rest-interface/>`_
is a full featured HTTP interface for MongoDB.
HTTP Status Interface
---------------------
MongoDB provides a simple HTTP interface listing information of interest
to administrators. If you enable the interface with the ``--rest``
option to :program:`mongod`, you may access it via a port that is
1000 more than the configured :program:`mongod` port. The default
port for the HTTP interface is ``28017``. To access the HTTP interface an
administrator may, for example, point a browser to
``http://localhost:28017`` if :program:`mongod` is running with the default port on the
local machine.
.. image:: /figures/http-interface-console.png
Here is a description of the informational elements of the HTTP
interface:
.. list-table::
:header-rows: 1
* - **element**
- **description**
* - db version
- database version information
* - git hash
- database version developer tag
* - sys info
- :program:`mongod` compilation environment
* - dblocked
- indicates whether the primary :program:`mongod` mutex is held
* - uptime
- time since this :program:`mongod` instance was started
* - assertions
- any software assertions that have been raised by this :program:`mongod` instance
* - replInfo
- information about replication configuration
* - currentOp
- most recent client request
* - # databases
- number of databases that have been accessed by this :program:`mongod` instance
* - curclient
- last database accessed by this :program:`mongod` instance
* - Cursors
- describes outstanding client cursors
* - master
- whether this :program:`mongod` instance has been designated a master
* - slave
- whether this :program:`mongod` instance has been designated a slave
* - initialSyncCompleted
- whether this slave or repl pair node has completed an initial
clone of the :program:`mongod` instance it is replicating
* - DBTOP
- Displays the total time the :program:`mongod` instance has devoted to each
listed collection, as well as the percentage of available time
devoted to each listed collection recently and the number of
reads, writes, and total calls made recently
* - dt
- Timing information about the primary :program:`mongod` mutex
HTTP Status Interface Security
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning:: Ensure that the HTTP status interface, the REST API, and
the JSON API are all disabled in production environments to prevent
potential data exposure and vulnerability to attackers.
See :ref:`Security and MongoDB API Interfaces <http-interface-security>`
If security is configured for a :program:`mongod` instance,
authentication is required for a client to access the HTTP status interface
from another machine.
.. note::
While MongoDB Enterprise does support Kerberos authentication,
Kerberos is not supported by the HTTP status interface in any
version of MongoDB.
.. versionchanged:: 3.0
Neither the HTTP status interface nor the REST API support the
:ref:`SCRAM-SHA-1 <authentication-scram-sha-1>` challenge-response
user authentication mechanism introduced in version 3.0.
Simple REST API
---------------
The :program:`mongod` process includes a simple REST API as a convenience. With no support for
insert, update, or remove operations, it is generally used
for monitoring, alert scripts, and administrative tasks. For full REST
capabilities, consider using an external :ref:`REST Interface <rest-interface>` such as
`Sleepy.Mongoose <http://www.kchodorow.com/blog/2010/02/22/sleepy-mongoose-a-mongodb-rest-interface/>`_.
**v1.4+**: This API is disabled by default, as it could provide unauthenticated access to data.
Use ``--rest`` on the command line to enable, but be aware of security implications.
To get the contents of a collection (note the trailing slash):
.. code-block:: sh
http://127.0.0.1:28017/databaseName/collectionName/
To add a limit:
.. code-block:: sh
http://127.0.0.1:28017/databaseName/collectionName/?limit=-10
To skip:
.. code-block:: sh
http://127.0.0.1:28017/databaseName/collectionName/?skip=5
To query for ``{a : 1}``:
.. code-block:: sh
http://127.0.0.1:28017/databaseName/collectionName/?filter_a=1
Separate conditions with an ``&``:
.. code-block:: sh
http://127.0.0.1:28017/databaseName/collectionName/?filter_a=1&limit=-10
Same as ``db.$cmd.findOne({listDatabase:1})`` on the ``admin`` database
in the shell:
.. code-block:: sh
http://localhost:28017/admin/$cmd/?filter_listDatabases=1&limit=1
To count documents in a collection:
.. code-block:: sh
http://host:port/db/$cmd/?filter_count=collection&limit=1
JSON in the simple REST API
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The simple REST API uses strict JSON (as opposed to the shell,
which uses Dates, regular expressions, etc.). To display non-JSON types,
the web interface wraps them in objects and uses the key for the type.
For example:
.. code-block:: sh
# ObjectIds just become strings
"_id" : "4a8acf6e7fbadc242de5b4f3"
# dates
"date" : { "$date" : 1250609897802 }
# regular expressions
"match" : { "$regex" : "foo", "$options" : "ig" }
The code type has not been implemented yet and causes the DB to crash if
you try to display it in the browser.
See :manual:`Mongo Extended JSON </reference/mongodb-extended-json/>`
for details.
Replica Set Admin UI
--------------------
The :program:`mongod` process includes a simple administrative UI for checking the
status of a replica set.
To use, first enable ``--rest`` from the :program:`mongod` command line. The rest port
is the db port plus 1000 (thus, the default is ``28017``). Be sure this port
is secure before enabling this.
Then you can navigate to ``http://<hostname>:28017/`` in your web
browser. Once there, click Replica Set Status
(`/_replSet <http://127.0.0.1:28017/_replSet>`_) to move to the Replica
Set Status page.
.. image:: /figures/http-interface-rs.png
See Also
--------
- :manual:`Monitoring Database Systems </administration/monitoring/>`
Jump to Line
Something went wrong with that request. Please try again.