| .. 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. |
| |
| .. _intro/curl: |
| |
| ============================== |
| cURL: Your Command Line Friend |
| ============================== |
| |
| The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X, |
| Windows, and many other platforms. ``curl`` provides easy access to the HTTP |
| protocol (among others) directly from the command line and is therefore an |
| ideal way of interacting with CouchDB over the HTTP REST API. |
| |
| For simple ``GET`` requests you can supply the URL of the request. For example, |
| to get the database information: |
| |
| .. code-block:: bash |
| |
| shell> curl http://admin:password@127.0.0.1:5984 |
| |
| This returns the database information (formatted in the output below for |
| clarity): |
| |
| .. code-block:: json |
| |
| { |
| "couchdb": "Welcome", |
| "version": "3.0.0", |
| "git_sha": "83bdcf693", |
| "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71", |
| "features": [ |
| "access-ready", |
| "partitioned", |
| "pluggable-storage-engines", |
| "reshard", |
| "scheduler" |
| ], |
| "vendor": { |
| "name": "The Apache Software Foundation" |
| } |
| } |
| |
| .. note:: |
| For some URLs, especially those that include special characters such as |
| ampersand, exclamation mark, or question mark, you should quote the URL you |
| are specifying on the command line. For example: |
| |
| .. code-block:: bash |
| |
| shell> curl 'http://couchdb:5984/_uuids?count=5' |
| |
| .. note:: |
| On Microsoft Windows, use double-quotes anywhere you see single-quotes in |
| the following examples. Use doubled double-quotes ("") anywhere you see |
| single double-quotes. For example, if you see: |
| |
| .. code-block:: bash |
| |
| shell> curl -X PUT 'http://127.0.0.1:5984/demo/doc' -d '{"motto": "I love gnomes"}' |
| |
| you should replace it with: |
| |
| .. code-blocK:: bash |
| |
| shell> curl -X PUT "http://127.0.0.1:5984/demo/doc" -d "{""motto"": ""I love gnomes""}" |
| |
| If you prefer, ``^"`` and ``\"`` may be used to escape the double-quote |
| character in quoted strings instead. |
| |
| You can explicitly set the HTTP command using the ``-X`` command line option. |
| For example, when creating a database, you set the name of the database in the |
| URL you send using a PUT request: |
| |
| .. code-block:: bash |
| |
| shell> curl -X PUT http://user:pass@127.0.0.1:5984/demo |
| {"ok":true} |
| |
| But to obtain the database information you use a ``GET`` request (with |
| the return information formatted for clarity): |
| |
| .. code-block:: bash |
| |
| shell> curl -X GET http://user:pass@127.0.0.1:5984/demo |
| { |
| "compact_running" : false, |
| "doc_count" : 0, |
| "db_name" : "demo", |
| "purge_seq" : 0, |
| "committed_update_seq" : 0, |
| "doc_del_count" : 0, |
| "disk_format_version" : 5, |
| "update_seq" : 0, |
| "instance_start_time" : "0", |
| "disk_size" : 79 |
| } |
| |
| For certain operations, you must specify the content type of request, which you |
| do by specifying the ``Content-Type`` header using the ``-H`` command-line |
| option: |
| |
| .. code-block:: bash |
| |
| shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids |
| |
| You can also submit 'payload' data, that is, data in the body of the HTTP |
| request using the ``-d`` option. This is useful if you need to submit JSON |
| structures, for example document data, as part of the request. For example, to |
| submit a simple document to the ``demo`` database: |
| |
| .. code-block:: bash |
| |
| shell> curl -H 'Content-Type: application/json' \ |
| -X POST http://user:pass@127.0.0.1:5984/demo \ |
| -d '{"company": "Example, Inc."}' |
| {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8", |
| "rev":"1-33b9fbce46930280dab37d672bbc8bb9"} |
| |
| In the above example, the argument after the ``-d`` option is the JSON of the |
| document we want to submit. |
| |
| The document can be accessed by using the automatically generated document ID |
| that was returned: |
| |
| .. code-block:: bash |
| |
| shell> curl -X GET http://user:pass@127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8 |
| {"_id":"8843faaf0b831d364278331bc3001bd8", |
| "_rev":"1-33b9fbce46930280dab37d672bbc8bb9", |
| "company":"Example, Inc."} |
| |
| The API samples in the :ref:`api/basics` show the HTTP command, URL and any |
| payload information that needs to be submitted (and the expected return value). |
| All of these examples can be reproduced using ``curl`` with the command-line |
| examples shown above. |