Skip to content

Fix debug endpoint for client certificate in REST API introduction, update REST API introduction page layout and texts #2553

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
reebhub wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fix debug endpoint for client certificate in REST API introduction, update REST API introduction page layout and texts #2553

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4672798
RDoc-2238 - Remove wrong debug endpoint for the client certificate in…
reebhub Jul 4, 2026
196b579
RDoc-3970 Update the REST API introduction page layout and texts
reebhub Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 102 additions & 98 deletions docs/client-api/rest-api/rest-api-intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,8 @@ sidebar_position: 0
---

import Admonition from '@theme/Admonition';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
import LanguageContent from "@site/src/components/LanguageContent";
import Panel from "@site/src/components/Panel";
import ContentFrame from "@site/src/components/ContentFrame";

# Introduction to the REST API
<Admonition type="note" title="">
Expand All @@ -24,144 +21,151 @@ import LanguageContent from "@site/src/components/LanguageContent";
* [HTTP guide for developers by Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP)
* [REST API Tutorial website](https://www.restapitutorial.com/)

* In this page:
* [cURL Basics](../../client-api/rest-api/rest-api-intro.mdx#curl-basics)
* [Document Format and Structure](../../client-api/rest-api/rest-api-intro.mdx#document-format-and-structure)
* [Using cURL With HTTPS](../../client-api/rest-api/rest-api-intro.mdx#using-curl-with-https)
* [Common HTTP Status Codes](../../client-api/rest-api/rest-api-intro.mdx#common-http-status-codes)
* In this article:
* [cURL Basics](../../client-api/rest-api/rest-api-intro.mdx#curl-basics)
* [Document Format and Structure](../../client-api/rest-api/rest-api-intro.mdx#document-format-and-structure)
* [Sending raw JSON using cURL](../../client-api/rest-api/rest-api-intro.mdx#sending-raw-json-using-curl)
* [Binary data](../../client-api/rest-api/rest-api-intro.mdx#binary-data)
* [Using cURL With HTTPS](../../client-api/rest-api/rest-api-intro.mdx#using-curl-with-https)
* [Common HTTP Status Codes](../../client-api/rest-api/rest-api-intro.mdx#common-http-status-codes)

</Admonition>
## cURL Basics

A good way to familiarize yourself with the RavenDB REST API is with the command line tool cURL, which allows you to construct and
<Panel heading="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](https://curl.haxx.se/download.html) (If you're using Linux
your CLI may already have cURL installed). You can learn how to use it with the [cURL documentation](https://curl.haxx.se/docs/).
This page just covers the basics you'll need to interact with RavenDB.
your CLI may already have cURL installed).
Learn how to use cURL using the [cURL documentation](https://curl.haxx.se/docs/), 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. This command retrieves the first document from
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](http://live-test.ravendb.net), and prints it in your CLI:

<TabItem value="bash" label="bash">
<CodeBlock language="bash">
{`curl http://live-test.ravendb.net/databases/demo/docs?pagesize=1
`}
</CodeBlock>
</TabItem>
```bash
curl http://live-test.ravendb.net/databases/demo/docs?pagesize=1
```
<br />

The other parameters of the HTTP request are specified using 'options'. These are the main cURL options that interest us:
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](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) that is sent with the request |
| -H | Add one or more headers, e.g. to provide extra information about the contents of the request body |
| -d | This option denotes the beginning of the body of the request. 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 |

This request uploads a document to a database on the playground server from a local file:

<TabItem value="bash" label="bash">
<CodeBlock language="bash">
{`curl -X PUT http://live-test.ravendb.net/databases/demo/docs?id=example -T <path to file>document.txt
`}
</CodeBlock>
</TabItem>
[More about how to upload documents](../../client-api/rest-api/document-commands/put-documents.mdx)
| -X | Set the [HTTP method](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) 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:

```bash
curl -X PUT http://live-test.ravendb.net/databases/demo/docs?id=example -T <path to file>document.txt
```
<br />

[More about how to upload documents](../../client-api/rest-api/document-commands/put-documents.mdx)

</Panel>

## Document Format and Structure
<Panel heading="Document Format and Structure">

In RavenDB all documents have a standard [JSON](https://www.json.org/) format. In essence, every JSON object is composed of a series
of key-value pairs. A document with a complex structure might look something like this:
of key-value pairs. A document with a complex structure might look similar to:

<TabItem value="json" label="json">
<CodeBlock language="json">
{`\{
```json
{
"<key>": <value>,
"<key>": "<string value>",
"an array": [
<value>,
"<string value>",
...
],
"an object": \{
"an object": {
"<key>": <value>,
"<key>": "<string value>",
...
\},
},
...
\}
`}
</CodeBlock>
</TabItem>

The whole object is wrapped in curly brackets `{}`. The `<key>` is always a string, and the `<value>` can be a string (denoted by
double quotes), a number, a boolean, or null. The value can also be an array of values wrapped in square brackets `[]`, or it can itself be another JSON object
wrapped in another pair of curly brackets. Whitespace is completely 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
needs to be on one line.


#### Sending raw JSON using cURL
Sending raw JSON in the body faces us with a problem: the 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. The solution is to escape every double quote
by putting a backslash `\` before it, like this:

<TabItem value="bash" label="bash">
<CodeBlock language="bash">
{`-d "\{
\\"a string\\": \\"some text\\",
\\"a number\\": 42
\}"
`}
</CodeBlock>
</TabItem>


#### Binary data
}
```
<br />

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.

<ContentFrame>

### 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:

```bash
-d "{
\"a string\": \"some text\",
\"a number\": 42
}"
```

</ContentFrame>

<ContentFrame>

### Binary data

In addition to JSON, pure binary data can be stored as an [attachment](../../document-extensions/attachments/overview.mdx)
associated with an existing document. Files can be added to the request with the `-T` option. Some types of requests, though, allow you to include raw binary in the body - such as the
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](../../client-api/rest-api/document-commands/batch-commands.mdx#put-attachment-command).

</ContentFrame>

</Panel>

## Using cURL With HTTPS
<Panel heading="Using cURL With HTTPS">

HTTPS adds public-key encryption on top of standard HTTP to protect information during transit between client and server. It has
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](../../start/installation/setup-wizard/overview.mdx) makes
it very simple to set up server secure using a free [Let's Encrypt](https://letsencrypt.org/) certificate.
it very simple to set up a secure server using a free [Let's Encrypt](https://letsencrypt.org/) certificate.

To communicate with a secure server over https, you need to specify the paths to the your client certificate and private key
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:

<TabItem value="bash" label="bash">
<CodeBlock language="bash">
{`curl --cert <path to your certificate file> --key <path to your private key file> "<server url>"
`}
</CodeBlock>
</TabItem>
```bash
curl --cert <path to your certificate file> --key <path to your private key file> "<server url>"
```
<br />

These files can be found in the configuration Zip package you received at the end of the setup wizard. You can download this Zip package
again by going to this endpoint: `<the URL of your server>/admin/debug/cluster-info-package`. The certificate and key are found at
the root of the package with the names: `admin.client.certificate.<your domain name>.crt`, and
`admin.client.certificate.<your domain name>.key` respectively.
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`

</Panel>

## Common HTTP Status Codes
<Panel heading="Common HTTP Status Codes">

These are a few of the HTTP status codes we use in our REST API, and what we mean by them:
Here are some of the HTTP status codes we use in our REST API, and their purpose:

| Code | [Official IANA description](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) | Purpose |
| - | - | - |
| 200 | OK | Indicates that a valid request was received by the server, such as `GET` requests and queries. 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 to tell the client that it can continue to use 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 |
| 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](../../server/clustering/replication/replication-conflicts.mdx). 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 | Used for exceptions that occur on the server side |


| 500 | Internal Server Error | Indicates exceptions that occur on the server side. |

</Panel>
Loading
Loading