Introduction to the REST API
-
This page covers some basic information that will help you learn to use the REST API:
- How to use the CLI tool cURL.
- A description of the JSON format for the purposes of writing and parsing it.
- Some of the HTTP status codes used in the API.
-
To learn more about HTTP and REST in general, try these tutorials:
-
In this article:
cURL Basics
A good way to familiarize yourself with the RavenDB REST API is to use the command line tool cURL, which allows you to construct and
send individual HTTP requests. You can download cURL from curl.haxx.se (If you're using Linux
your CLI may already have cURL installed).
Learn how to use cURL using the cURL documentation, this page covers only the basics needed to interact with RavenDB.
All cURL commands begin with the keyword curl and contain the URL of your RavenDB server or one of its endpoints.
The following command retrieves the first document from
a database named "Demo" located on our public playground server, and prints it in your CLI:
curl http://live-test.ravendb.net/databases/demo/docs?pagesize=1
The other parameters of the HTTP request are specified using options.
The following cURL options are of special interest to us:
| Option | Purpose |
|---|---|
| -X | Set the HTTP method that is sent with the request. |
| -H | Add one or more headers, e.g., to provide extra information about the content of the request body. |
| -d | This option denotes the beginning of the request's message body. The body itself is wrapped with double quotes ". One of the ways to upload a document to the server is to send it in the body. |
| -T | Set the path to a file you want to upload, such as a document or attachment. |
| --cert | (For https) the path to your certificate file. |
| --key | (For https) the path to your private key file. |
The following request uploads a document to a database on the playground server from a local file:
curl -X PUT http://live-test.ravendb.net/databases/demo/docs?id=example -T <path to file>document.txt
Document Format and Structure
In RavenDB all documents have a standard JSON format. In essence, every JSON object is composed of a series of key-value pairs. A document with a complex structure might look similar to:
{
"<key>": <value>,
"<key>": "<string value>",
"an array": [
<value>,
"<string value>",
...
],
"an object": {
"<key>": <value>,
"<key>": "<string value>",
...
},
...
}
The whole object is wrapped in curly brackets {}:
- The
<key>is always a string. - The
<value>can be a string (denoted by double quotes), a number, a boolean, or null.
It can also be an array of values wrapped in square brackets[], or another JSON object wrapped in another pair of curly brackets.
Whitespace is optional. In the above example and throughout the documentation, JSON is broken into multiple lines for the sake of clarity. When using cURL, the entire command, including the request body, must be sent on a single line.
Sending raw JSON using cURL
Sending raw JSON introduces a problem: the message body itself is wrapped with double quotes ",
so the double quotes within the JSON will be interpreted by the parser as the end of the body.
To solve this, escape every double quote using \, like so:
-d "{
\"a string\": \"some text\",
\"a number\": 42
}"
Binary data
In addition to JSON, pure binary data can be stored as an attachment
associated with an existing document. Files can be added to the request with the -T option. Some request types, however, allow you to include raw binary in the message body, e.g., the
Put Attachment Command.
Using cURL With HTTPS
HTTPS adds public-key encryption on top of standard HTTP, to protect information during transit between client and server. Using HTTPS has become increasingly common throughout the internet in recent years. Our setup wizard makes it very simple to set up a secure server using a free Let's Encrypt certificate.
To communicate with a secure server over https, you need to specify the paths to your client certificate and private key
files with the --cert and --key options respectively:
curl --cert <path to your certificate file> --key <path to your private key file> "<server url>"
The certificate and key files can be found in the configuration Zip package you received at the end of the setup wizard, at the package root, bearing these names:
- Certificate -
admin.client.certificate.<your domain name>.crt - Key -
admin.client.certificate.<your domain name>.key
Common HTTP Status Codes
Here are some of the HTTP status codes we use in our REST API, and their purpose:
| Code | Official IANA description | Purpose |
|---|---|---|
| 200 | OK | Indicates that a valid request was received by the server, such as a GET request or a query. This includes cases where the response body itself is empty because the query returned 0 results. |
| 201 | Created | Confirms the success of document PUT requests. |
| 304 | Not Modified | When prompted, the server can check if the requested data has been modified since the previous request. If it hasn't, the server responds with this status code indicating to the client it can continue using the locally cached copy of the data. This is a mechanism we often use to minimize traffic over the network. |
| 404 | Not Found | Sometimes used to indicate that the request was valid but the requested data could not be found. |
| 409 | Conflict | Indicates that the database has received conflicting commands. This happens in clusters when different nodes receive commands to modify the same data at the same time - before the modification could be passed on to the rest of the cluster. |
| 500 | Internal Server Error | Indicates exceptions that occur on the server side. |