Chapter 11. RavenDB HTTP API

RavenDB allows interactions over the HTTP protocol and is exposing itself as a RESTful web service.

In this chapter, you will learn how to access the RavenDB server using technologies other than .NET and without using the Management Studio. The RavenDB HTTP API allows communicating with it using the HTTP protocol.

You will learn about the REST main verbs and how to use them to retrieve documents from RavenDB or add documents to the database. To simplify the REST requests composition, you will use an HTTP tool to do some interaction with RavenDB through the RavenDB RESTful API.

In this chapter we will cover:

• The RavenDB HTTP API

• Performing requests using the main REST verbs (GET, PUT, POST, PATCH, and DELETE)

• Retrieving multiple documents

• Querying Indexes

The RavenDB HTTP API

RavenDB fully supports an API based on HTTP that basically permits to interact with the database engine with simple HTTP requests. This means that if you have an application or environment that can talk HTTP, you can communicate through the RavenDB HTTP API. This HTTP API follows commonly understood RESTful principles and the interactions are entirely based around the HTTP protocol. When using the HTTP protocol to access RESTful resources, the resource identifier is the URL of the resource and the standard operation to be performed on that resource is one of the HTTP methods such as GET, PUT, DELETE, POST, or HEAD. RavenDB is exposing itself as the RESTful web service. Utilizing a RESTful HTTP API allows an application functionality to be consistently used across different platforms. It's possible to write a fully functioning RavenDB application just using JavaScript, HTML, and the HTTP API.

Understanding REST

REST is an architectural paradigm and RESTful is used as an adjective describing something that respects the REST constraints. REST stands for REpresentational State Transfer. It is a way of interacting with resources on the web via plain human-readable URLs.

Any interaction of a RESTful API is an interaction with a resource. In fact, the API can be considered simply as mapping and endpoint—or resource identifier (URL)—to a resource. Resources are sources of information, typically documents or services. An HTTP-based REST API makes communicating with the database easier, because so many modern environments are capable of talking HTTP. The simple structure of HTTP resources and methods is easy to understand and develop with.

The REST interface defines four commonly used HTTP main verbs: GET, POST, PUT, and DELETE, and others that are not used as often such as HEAD, OPTIONS, and so on. Each verb has certain characteristics and it is critical to choose the right verb.

The GET...

Anatomy of the RavenDB REST request URL

REST requests are URL-based. In order to get or put any document in RavenDB, we will basically create a request and use a RavenDB target structure. Then we will specify what type of entity it is and the document ID or the data to be sent to the server within the URL. To create the RavenDB REST request, we will make a request to a specific URL that will look like:

• url: This represents the URL where RavenDB is running.

• port: This is the TCP port number, by default the port number is 8080.

• databaseName: This is the name of the database where the documents are stored.

• target: This represents the target structure in RavenDB we want to deal with. This might be the docs structure, the indexes structure, the queries structure, and so on.

• RequestData: This represents the data resources for the request. It might be the document ID on which the action is performed (create, retrieve, update, or delete) or all other data needed to perform the action.

The RESTClient tool

To experiment and interact with the RavenDB HTTP API, we need to use a REST client tool to create HTTP requests and display HTTP responses easily. We will use the RESTClient tool, which is an open source Java application for composing and submitting the HTTP REST requests to the RavenDB server and for viewing and analyzing the RavenDB server responses.

The RESTClient graphic interface is divided into two main sections:

1. The HTTP Request screen section: This screen section has several tabs to view and manage the parameters of the generated request that will be sent to the server. We can choose the HTTP action method to perform on the server, change the request header if we need to, and to do all the things we need to do to interact with the RavenDB web service.

2. The HTTP Response screen section: This screen section has many tabs that shows the metadata included in the header of the server response and the document body data in colored plain text format.

   

Time for action – downloading and launching the RESTClient tool

Let us start by downloading the RESTClient tool to begin using the RavenDB HTTP API:

1. Open your web browser and go to this URL: http://www.wiztools.org/.

2. In the projects list click on the RESTClient link.

3. Download the RESTClient 3.1 GUI Executable Jar file.

   Note

   At the time of writing, RESTClient v3.1 GUI was the latest version. If a newer stable release is available, you should download that version instead.

4. Once downloaded, double-click on the JAR file to launch the RESTClient tool.

   Note

   RESTClient requires a Java Runtime Environment (JRE) to run, which might be already installed on your system. If the JRE is not present on your system, please install the latest JRE from http://www.java.com before installing and launching RESTClient.

What just happened?

We just downloaded the latest version of the open source Java application RESTClient to compose REST requests easily.

We will use this third party tool to create the HTTP requests that...

The GET request

The GET verb is used for read-only operations. There are no side effects for which the client is responsible. So GET should not be used to update or delete a resource or to make a new resource. Every system that understands the HTTP protocol assumes that a GET request will not change the state of the system and hence will make assumptions based on that.

In order to get any document in RavenDB, we will basically create a GET request and use the RavenDB docs structure. Then we will specify the type of entity which will hold the document data and the document ID we want to retrieve from the server.

Once the GET request is sent to RavenDB in order to retrieve a given document, it will respond with the contents of that document and an HTTP response code:

HTTP Method	On Success	On Error
GET	HTTP/1.1 200 OK HTTP/ 1.1 304 Not Modified	HTTP/1.1 404 Not Found

Time for action – performing a GET request

You will learn to create a GET request using the RESTClient tool we have downloaded in the previous section to retrieve the document with the ID = Orders/A655302 from the Orders database and view it. (We created the Orders database in Chapter 2, RavenDB Management Studio.)

1. If it is not already open, double-click on the RESTClient tool's JAR file in order to launch it.

2. Click on the Method tab and select the GET HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/docs/orders/a655302.

   

   Note

   To perform this GET request, we don't need to change any of the Header or the Body, or other parameters.

4. Click on the green Go! button to send your first request to the server.

What just happened?

You just created your first GET request to retrieve the order document with the ID Orders/A655302 from the Orders database directly by using the RavenDB HTTP API.

Let's have a look at the server response and analyze it. The first thing...

The PUT request

The PUT verb is an HTTP method that can be used to create a resource, with the information in the request, for the URL specified by the client. It is important to note that a PUT verb in RavenDB will always create the specified document at the requested URL. If the resource already exists, PUT simply replaces what existed with the new information.

In order to put any document into RavenDB, we will create a PUT request and use the docs structure. We have to specify the document ID and the document data in JSON format. Also, we need to specify the name of the collection to which the document will belong. The PUT request URL is similar to the GET request URL we created in the previous section.

In case that a PUT request is sent to the RavenDB's docs structure without specifying the document ID in the request URL, this request is considered as invalid and RavenDB will return an HTTP error response code.

Once the request is sent to RavenDB, it will respond with the ID of the document...

Time for action – granting access to perform a PUT request

Performing a PUT request needs writing privileges on the server. By default, RavenDB grants a read-only access to anonymous users. You will change the Raven/AnonymousAccess key value which is Get by default and set it to All which will allow you to add new documents to the RavenDB server:

1. Shutdown the RavenDB server and close the Management Studio.

2. Open the Raven.Server.exe.config file located in the \Server folder of the RavenDB installation folder.

3. Change the Raven/AnonymousAccess key value and set it to All.

4. Save the Raven.Server.exe.config file and launch the RavenDB server using the Start.cmd file.

   

What just happened?

By default, RavenDB grants the read-only permission for anonymous users.

In order to allow write operation and grant anonymous users permission to add a new document to the RavenDB server, we change the Raven/AnonymousAccess key's value and set it to All.

Time for action – performing a PUT request

We will add a new document to the Orders database by creating a PUT request using the RESTClient tool. The new document will have the ID = Orders/C676332 and will be added to the Orders collections which belongs to the Orders database.

Once the document is added to the server, we will take a look at the server response. Then, we will open the Management Studio and verify that the document has been correctly added to the server:

1. Launch the RESTClient tool.

2. Click on the Method tab and select the PUT HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/docs/Orders/C676332.

4. Click on the Body tab and select String body from the drop-down list and enter the following JSON snippet:

   {
     "CustomerId": "A55689",
     "Item": "Mouse Pad",
     "OrderDate": "11/3/2011",
     "UnitCost": 8.5,
     "Units": 10
   }

5. Click on the Header tab and enter Raven-Entity-Name in the Key textbox and Orders in the Value textbox and then click on the...

The POST request

The POST verb can be used to either create a resource or update an existing resource. All HTTP aware components assume that POST will make a change to the state of the system and will not repeat a POST request in case of an error.

When we perform a POST request to the RavenDB's docs structure, it will create the specified document and allow RavenDB to assign a unique ID to it. We have to specify the document data in JSON format and will not specify the document ID. It is important to note that a repeated POST request for the same document will create that document with a new ID each time.

The POST request URL is very similar to the PUT request URL with the difference that we do not specify the document ID in the URL.

A POST request to a document URL is considered as an invalid request and RavenDB will return error status code. Otherwise, if the POST request succeeded, the server response will contain the generated ID for the document and an HTTP response code:

Time for action – performing a POST request

You will add a new document to the Orders database by creating a POST request using the RESTClient tool. As RavenDB will generate the ID for the new document, we will not specify any ID for the document. Once the document is added to the database on the server, we will open the Management Studio and verify that the document has been correctly inserted into the database and we will analyze the server response:

1. Launch the RESTClient tool.

2. Click on the Method tab and select the POST HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/docs.

4. Click on the Body tab and select String body from the drop-down list and enter the following JSON snippet:

   {
     "CustomerId": "B66689",
     "Item": "USB Key",
     "OrderDate": "1/7/2012",
     "UnitCost": 28.5,
     "Units": 5
   }

5. Click on the Header tab and enter Raven-Entity-Name in the Key textbox and Orders in the Value textbox and then click on the green plus sign to add this metadata...

The PATCH request

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the request URL. The set of changes is represented in a format called the Patch Document. The PATCH method affects the resource identified by the request URL.

Within the RavenDB server, the PATCH request allows any single document to be updated without replacing the entire document as it is happening with the PUT request. The PATCH command accepts an array of commands, so it is possible to issue multiple modifications for the same document. The PATCH command keys are case sensitive and they have to be specified with the correct Pascal Casing. The six different command keys which you need to specify are listed as follows:

1. Type: This represents the operation type. RavenDB supports the following patch operations:

   • Set: It is a property to a new value. (Optionally, creating the property).

   • Inc: Use this to increment a property value by a given value. (Optionally...

Time for action – performing a Patch request

You will open the document you just added to the Orders database using the Management Studio in order to copy its ID. Then, you will patch this document using the PATCH request. The patch request will add two new fields to the document: Colour and Discount. After that, you will view the modified document in the Management Studio:

1. Open the Management Studio and select the Orders database.

2. Click on the Documents tab and open the document which has a Guid as ID.

3. Copy the document ID to the clipboard.

4. Launch the RESTClient tool.

5. Click on the Method tab and select the PATCH HTTP method.

6. In the HTTP Request section, enter this URL and complete it by the document Guid you stored on the clipboard: http://localhost:8080/databases/orders/docs/{your Guid}.

7. Click on the Header tab and ensure that the Raven-Entity-Name metadata key is sent to the RavenDB server with the Value = Orders.

8. Click on the Body tab and select String Body in the drop-down list.

9. Enter the following...

The DELETE request

The DELETE verb asks the server to delete the resources. This will instruct RavenDB to delete the JSON document specified by the URL. It is important to note that deleting a document through the HTTP API is not reversible and has to be considered as a "hard" delete.

To avoid potential data loss, you can use a soft delete and there are multiple ways to do that. You may choose to move the existing documents to another database, or to mark a document with a deleted flag and then ignore documents like this in your business logic.

If the document we want to delete exists on the server or it doesn't exist, a DELETE request will still respond with a successful status code.

HTTP Method	...

HTTP Method	On Success
DELETE	HTTP/1.1 204 No Content

Time for action – performing a POST request

You will add a new document to the Orders database by creating a POST request using the RESTClient tool. As RavenDB will generate the ID for the new document, we will not specify any ID for the document. Once the document is added to the database on the server, we will open the Management Studio and verify that the document has been correctly inserted into the database and we will analyze the server response:

1. Launch the RESTClient tool.

2. Click on the Method tab and select the POST HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/docs.

4. Click on the Body tab and select String body from the drop-down list and enter the following JSON snippet:

   {
     "CustomerId": "B66689",
     "Item": "USB Key",
     "OrderDate": "1/7/2012",
     "UnitCost": 28.5,
     "Units": 5
   }

5. Click on the Header tab and enter Raven-Entity-Name in the Key textbox and Orders in the Value textbox and then click on the green plus sign to add this metadata...

The PATCH request

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the request URL. The set of changes is represented in a format called the Patch Document. The PATCH method affects the resource identified by the request URL.

Within the RavenDB server, the PATCH request allows any single document to be updated without replacing the entire document as it is happening with the PUT request. The PATCH command accepts an array of commands, so it is possible to issue multiple modifications for the same document. The PATCH command keys are case sensitive and they have to be specified with the correct Pascal Casing. The six different command keys which you need to specify are listed as follows:

1. Type: This represents the operation type. RavenDB supports the following patch operations:

   • Set: It is a property to a new value. (Optionally, creating the property).

   • Inc: Use this to increment a property value by a given value. (Optionally...

Time for action – performing a Patch request

You will open the document you just added to the Orders database using the Management Studio in order to copy its ID. Then, you will patch this document using the PATCH request. The patch request will add two new fields to the document: Colour and Discount. After that, you will view the modified document in the Management Studio:

1. Open the Management Studio and select the Orders database.

2. Click on the Documents tab and open the document which has a Guid as ID.

3. Copy the document ID to the clipboard.

4. Launch the RESTClient tool.

5. Click on the Method tab and select the PATCH HTTP method.

6. In the HTTP Request section, enter this URL and complete it by the document Guid you stored on the clipboard: http://localhost:8080/databases/orders/docs/{your Guid}.

7. Click on the Header tab and ensure that the Raven-Entity-Name metadata key is sent to the RavenDB server with the Value = Orders.

8. Click on the Body tab and select String Body in the drop-down list.

9. Enter the following...

The DELETE request

The DELETE verb asks the server to delete the resources. This will instruct RavenDB to delete the JSON document specified by the URL. It is important to note that deleting a document through the HTTP API is not reversible and has to be considered as a "hard" delete.

To avoid potential data loss, you can use a soft delete and there are multiple ways to do that. You may choose to move the existing documents to another database, or to mark a document with a deleted flag and then ignore documents like this in your business logic.

If the document we want to delete exists on the server or it doesn't exist, a DELETE request will still respond with a successful status code.

Time for action – performing a Delete request

You will delete the document just added to the Orders database using a DELETE request. You will specify the document Guid in the request URL and perform the request on the server to delete the document. Then, you will verify in the Management Studio that the document has been removed and you will take a look to the server response:

1. Open the Management Studio and select the Orders database.

2. Click on the Documents tab and open the document which has a Guid as the ID.

3. Copy the document ID to the clipboard.

4. Launch the RESTClient tool.

5. Click on the Method tab and select the DELETE HTTP method.

6. In the HTTP Request section, enter this URL and complete it by the document Guid you stored on the clipboard: http://localhost:8080/databases/orders/docs/{your guid}.

7. Click on the green Go! button to send the DELETE request to the server.

8. In the Management Studio, click on the Documents tab and verify that the document has been deleted from the Orders database.

   

What...

Getting multiple documents with a single request

You may need, in your application, to get back multiple documents from RavenDB directly. In order to avoid sending to the server multiple queries, RavenDB supports the ability to get multiple documents in a single call. The way to do this is to create a POST request that we will post to a special URL.

Note

Getting multiple documents via one single call is also exposed via a GET method.

Instead of posting to the docs area structure, we will address the queries area and in the body of our POST request, we will specify a JSON array of all IDs we want to get back from RavenDB. The response for such a request is a JSON object that consists of two arrays of documents: Results and Includes. Each document also includes the metadata.

The Results array has documents that we asked for, while the Includes array contains optionally referenced documents. To determine what reference you want to retrieve together with a document an include parameter has to be...

Time for action – getting multiple documents within a single request

You will learn to retrieve two documents in a single remote call from the Orders database using a POST request. You will specify the documents IDs in the request body and perform the request on the server to retrieve documents. Then, you will view the server response in the RESTClient tool:

1. Launch the RESTClient tool.

2. Click on the Method tab and select the POST HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/queries/.

4. Click on the Body tab and select String Body in the drop-down list and enter the following code snippet:

   [ 'Orders/C676332','Orders/A179854' ]

   Note

   We have to arbitrarily choose two document IDs from the Orders database.

5. Click on the green Go! button to send the POST request to the server.

   

What just happened?

We retrieved two documents from the Orders database using a single POST request addressed to the queries structure.

In the request body, we specify a JSON array...

Querying an Index

Querying a RavenDB Index is basically a GET request to a special URL. An index may be generated by the server as a result of the query.

The GET request is addressed to the indexes special RavenDB area structure. The result for this request is a JSON object which contains the array Results and many fields such as IsStale and TotalResults. IsStale is a boolean indicator of whether or not this index (and results) are up to date, and TotalResults is the count of the matching records.

When an index is first created or when new documents are added that could be part of the index, RavenDB runs a background process to update the index. If this process is running while an index query is issued, then the last known results will be returned, but clearly marked as stale with IsStale set to true.

Time for action – querying an Index

We will query the TotalOrdersPerCustomer index from the Orders database which we created in the previous chapter. You will use the RESTClient tool to send the request to RavenDB and view the server response and analyze it:

1. Launch the RESTClient tool.

2. Click on the Method tab and select the GET HTTP method.

3. In the HTTP Request section, enter this URL: http://localhost:8080/databases/orders/indexes/TotalOrdersPerCustomer.

4. Click on the green Go! button to send the GET request to the server.

   

What just happened?

We queried the TotalOrdersPerCustomer index from the Orders database using a GET request addressed to the indexes structure.

The server response is a JSON object that contains the arrays: Results which contains all returned documents by the index and Includes. Also, in the server response, we have two fields: IsStale the value of which is false and the TotalResults the value of which is set to 4 which is the documents count that have been returned by the...

Summary

We learned a lot in this chapter about RavenDB's RESTful API and the main REST verbs that you can use to interact with RavenDB over HTTP.

Specifically, we covered the RavenDB HTTP API REST requests basics and anatomy and introduce a third party tool, the RESTClient which we used to compose and send requests to the RavenDB server.

We learned about the main REST verbs used to address the RavenDB server over HTTP and talked about GET, PUT, POST, PATCH and DELETE requests.

Also we learned how to get multiple documents in one single remote call and how to query an index using the RavenDB HTTP API.

There are more advanced commands but we covered what will give us a good understanding if we want to query RavenDB directly from our web page or other technologies that do not use the .NET Client.

In the next chapter, we will present the basics of building an ASP.NET MVC 4 web application that uses and interacts with RavenDB. Keep reading!