Skip to content
fromorbonia edited this page Jan 6, 2013 · 25 revisions

OrientDB RESTful HTTP Protocol

Introduction

OrientDB RESTful HTTP protocol allows to talk with a OrientDB Server instance using the HTTP protocol and JSON. OrientDB supports also a highly optimized Binary protocol for superior performances.

HTTP Methods

This protocol uses the four methods of the HTTP protocol:

  • GET, to retrieve values from the database. It's idempotents that means no changes to the database happen. Remember that in IE6 the URL can be maximum of 2,083 characters. Other browsers supports major length, but if you want to stay compatible with all limit to 2,083 characters
  • POST, to insert values into the database
  • PUT, to change values into the database
  • DELETE, to delete values from the database

When using POST and PUT the following are important when preparing the contents of the post message:

  • Always have the content type set to “application/json” or "application/xml"
  • Where data or data structure is involved the content is in JSON format
  • For OrientDB SQL or Gremlin the content itself is just text

Syntax

The REST API is very flexible, with the following features:

  • Data returned is in JSON format
  • JSONP callback is supported
  • Support for http and https connections
  • The API itself is case insensitive
  • API can just be used as a wrapper to retrieve (and control) data through requests written in OrientDB SQL or Gremlin

The REST syntax used is the same for all the four HTTP methods:

Syntax: http://<server>:<port>/<command>/[<database>/<arguments>]

Results are always in JSON format. Support for 'document' object types is through the use of the attribute @type : 'd'. This also applies when using inner document objects. Example:

    {
      "@type"  : "d"
      "Name"   : "Test",
      "Data"   : { "@type": "d",
                   "value": 0 },
      "@class" : "SimpleEntity"
    }

JSONP is also supported by adding a callback parameter to the request (containing the callback function name).

Syntax: http://<server>:<port>/<command>/[<database>/<arguments>]?callback=<callbackFunctionName>

Commands are divided in two main categories:

  • Server commands, such as to know server statistics and to create a new database
  • Database commands, all the commands against a database

Authentication and security

All the commands (but the Disconnect need a valid authentication before to get executed. The OrientDB Server checks if the Authorization HTTP header is present, otherwise answers with a request of authentication (HTTP error code: 401).

The HTTP client (or the Internet Browser) must send user and password using the HTTP Base authentication. Password is encoded using Base64 algorithm. Please note that if you want to encrypt the password using a safe mode take in consideration to use SSL connections.

Server commands use the realm "OrientDB Server", while the database commands use a realm per database in this form: "OrientDB db-<database>", where <database> is the database name. In this way the Browser/HTTP client can reuse user and password inserted multiple times until the session expires or the "Disconnect" is called.

JSON data type handling and Schema-less mode

Since OrientDB supports also schema-less/hybrid modes how to manage types? JSON doesn't support all the types OrientDB has, so how can I pass the right type when it's not defined in the schema?

The answer is using the special field "@fieldTypes" as string containing all the field types separated by comma. Example:

    { "@class":"Account", "date": 1350426789, "amount": 100.34, "@fieldTypes": "date=t,amount=c" }

The supported special types are:

  • 'f' for float
  • 'c' for decimal
  • 'l' for long
  • 'd' for double
  • 'b' for byte and binary
  • 'a' for date
  • 't' for datetime
  • 's' for short

HTTP commands

Connect

GET - Connect

Syntax: http://:[]/connect/

Example

HTTP GET request: http://localhost:2480/connect/demo HTTP response:

    {
    {
        "server": {
            "version": "1.1.0-SNAPSHOT",
            "osName": "Windows 7",
            "osVersion": "6.1",
            "osArch": "amd64",
            "javaVendor": "Oracle Corporation",
            "javaVersion": "23.0-b21"
        }, "classes": [
        {
          "id": 0, 
          "name": "ORole", 
          "clusters": [3], 
          "defaultCluster": 3, "records": 0}, 
    ...

Class

GET - Class

Gets informations about requested class.

Syntax: http://<server>:[<port>](<port>]/connect/<database>/class/<database>/<class-name>

HTTP response:

    { "class": {
        "name": "<class-name>"
        "properties": {
          <property-name> : {
             "name": <property-name>,
             "type": <property-type>,
             "mandatory": <mandatory>,
             "notNull": <not-null>,
             "min": <min>,
             "max": <max>
           }
        }
      }
    }

For more information about properties look at the supported types, or see the SQL Create property page for text values to be used when getting or posting class commands

Example

HTTP GET request: http://localhost:2480/class/demo/Address HTTP response:

    {
        "class": {
            "name": "Account",
            "properties": {
                "id": {
                    "name": "id",
                    "type": "INTEGER",
                    "mandatory": false,
                    "notNull": false,
                    "min": null,
                    "max": null
                },
                "binary": {
                    "name": "binary",
                    "type": "BINARY",
                    "mandatory": false,
                    "notNull": false,
                    "min": null,
                    "max": null
                },
                "birthDate": {
                    "name": "birthDate",
                    "type": "DATE",
                    "mandatory": false,
                    "notNull": false,
                    "min": null,
                    "max": null
                }
            }
        }
    }

POST - Class

Create a new class where the schema of the vertexes or edges is known. OrientDB allows (encourages) classes to be derived from other class definitions – this is achieved by using the COMMAND call with an OrientDB SQL command. Returns the id of the new class created.

Syntax: http://<server>:[<port>]/class/<database>/<class-name>

HTTP POST request: http://localhost:2480/class/demo/Address2 HTTP response: 9

Property

POST - Property

Create one or more properties into a given class. Returns the number of properties of the class.

Single property creation

Syntax: http://<server>:[<port>]/property/<database>/<class-name>/<property-name>/[<property-type>]

Creates a property named <property-name> in <class-name>. If <property-type> is not specified the property will be created as STRING.

Multiple property creation

Syntax: http://<server>:[<port>]/property/<database>/<class-name>/

Requires a JSON document post request content:

    {
        "fieldName": {
            "propertyType": "<property-type>"
        },
        "fieldName": {
            "propertyType": "LINK",
            "linkedClass": "<linked-class>"
        },
        "fieldName": {
            "propertyType": "<LINKMAP|LINKLIST|LINKSET>",
            "linkedClass": "<linked-class>"
        },
        "fieldName": {
            "propertyType": "<LINKMAP|LINKLIST|LINKSET>",
            "linkedType": "<linked-type>"
        }
    }

Example

Single property:

String Property Example: HTTP POST request: http://localhost:2480/class/demo/simpleField HTTP response: 1

Type Property Example: HTTP POST request: http://localhost:2480/class/demo/dateField/DATE HTTP response: 1

Link Property Example: HTTP POST request: http://localhost:2480/class/demo/linkField/LINK/Person HTTP response: 1

Multiple properties: HTTP POST request: http://localhost:2480/class/demo/ HTTP POST content:

    {
        "name": {
            "propertyType": "STRING"
        },
        "father": {
            "propertyType": "LINK",
            "linkedClass": "Person"
        },
        "addresses": {
            "propertyType": "LINKMAP",
            "linkedClass": "Address"
        },
        "examsRatings": {
            "propertyType": "LINKMAP",
            "linkedType": "INTEGER"
        }
        "events": {
            "propertyType": "LINKLIST",
            "linkedType": "DATE"
        }
        "family": {
            "propertyType": "LINKLIST",
            "linkedClass": "Person"
        }
    ...

HTTP response: 6

Cluster

GET - Cluster

Where the primary usage is a document db, or where the developer wants to optimise retrieval using the clustering of the database, use the CLUSTER command to browse the records of the requested cluster.

Syntax: `http://:[

Where <limit> is optional and tells the maximum of records to load. Default is 20.

Example

HTTP GET request: http://localhost:2480/cluster/demo/Address

HTTP response:

    { "schema": {
        "id": 5, 
        "name": "Address"
      }, 
      "result": [{
          "_id": "11:0", 
          "_ver": 0, 
          "@class": "Address", 
          "type": "Residence", 
          "street": "Piazza Navona, 1", 
          "city": "12:0"
        }
    ...

Command

### POST - Command ###

Execute a command against the database. Returns the records affected or the list of records for queries. Command executed via POST can be non-idempotent (look at Query).

Syntax: http://<server>:[<port>]/command/<database>/<language>[/<command-text>][/limit][/<fetchPlan>] content: <command-text>

Where:

  • <language> is the name of the language between those supported. OrientDB distribution comes with "sql" and GraphDB distribution has both "sql" and "gremlin"
  • command-text is the text containing the command to execute
  • limit is the maximum number of record to return. Optional, default is 20
  • fetchPlan is the fetching strategy to use. For more information look at Fetching Strategies. Optional, default is *:1 (1 depth level only)

The command-text can appear in either the URL or the content of the POST transmission.

Where the command-text is included in the URL, it must be encoded as per normal URL encoding.

Read the SQL section or the Gremlin introduction for the type of commands.

Example

HTTP POST request: http://localhost:2480/command/demo/sql content: update Profile set online = false

HTTP response: 10

Or the same:

HTTP POST request: http://localhost:2480/command/demo/sql/update Profile set online = false

HTTP response: 10

Function

POST and GET - Function

Executes a server-side function against the database. Returns the result of the function that can be a string or a JSON containing the document(s) returned.

The difference between GET and POST method calls are if the function has been declared as idempotent. In this case can be called also by GET, otherwise only POST is accepted.

Syntax: `http://:[]/function//[/*]

Where

  • <name> is the name of the function
  • <argument>, optional, are the arguments to pass to the function. They are passed by position.

Creation of functions, when not using the Java API, can be done through the Studio in either Orient DB SQL or Java – see the OrientDB Functions page.

Example

HTTP POST request: http://localhost:2480/function/demo/sum/3/5

HTTP response: 8.0

Database

GET - Database

Retrieve all the information about a database.

Syntax: http://<server>:[<port>]/database/<database>

Example

HTTP GET request: http://localhost:2480/database/demo

HTTP response:

    {"classes": [
        {
          "id": 0, 
          "name": "ORole", 
          "clusters": [3], 
          "defaultCluster": 3, "records": 0}, 
        {
          "id": 1, 
          "name": "OUser", 
          "clusters": [4], 
          "defaultCluster": 4, "records": 0}, 
        {
    ...

POST - Database

Create a new database. Requires additional authentication to the server.

Syntax for the url `http://:

  • storage can be
  • 'local' for disk-based database
  • 'memory' for in memory only database.
  • type, is optional, and can be document or graph. By default is a document.

Example

HTTP POST request: http://localhost:2480/database/demo2/local HTTP response:

    {"classes": [
        {
          "id": 0, 
          "name": "ORole", 
          "clusters": [3], 
          "defaultCluster": 3, "records": 0}, 
        {
          "id": 1, 
          "name": "OUser", 
          "clusters": [4], 
          "defaultCluster": 4, "records": 0}, 
        {
    ...

DELETE - Database

Drop a database. Requires additional authentication to the server.

Syntax: http://<server>:[<port>]/database/<databaseName>

Where:

  • databaseName is the name of database

Example

HTTP DELETE request: http://localhost:2480/database/demo2 HTTP response code 204

Export

GET - Export

Exports a gzip file that contains the database JSON export.

Syntax: http://:[]/export/

HTTP GET request: http://localhost:2480/export/demo2 HTTP response: demo2.gzip file

List Databases

GET - List Databases

Retrieves the available databases.

Syntax: http://<server>:<port>/listDatabases

To let to the Studio to display the database list by default the permission to list the database is assigned to guest. Remove this permission if you don't want anonymous user can display it.

For more details see Server Resources

Example of configuration of "guest" server user: a15b5e6bb7d06bd5d6c35db97e51400b

Example

HTTP GET request: http://localhost:2480/listDatabases HTTP response:

    {
      "@type": "d", "@version": 0, 
        "databases": ["demo", "temp"]
          }

Import

POST - Import

Imports a database from an uploaded JSON text file.

Syntax: http://<server>:[<port>]/import/<database>

Important: Connect required: the connection with the selected database must be already established

Example

HTTP POST request: http://localhost:2480/import/ HTTP response: returns a JSON object containing the result text Success:

    {
    "responseText": "Database imported correctly"
    }

_Fail::

    {
    "responseText": "Error message"
    }
##Disconnect##

GET - Disconnect

Syntax: http://<server>:[<port>]/disconnect

Example

HTTP GET request: http://localhost:2480/disconnect HTTP response: empty.

Document

GET - Document

This is a key way to retrieve data from the database, especially when combined with a <fetchplan>. Where a single result is required then the RID can be used to retrieve that single document.

Syntax: http://<server>:[<port>]/document/<database>/<record-id>[/<fetchPlan>]

Where:

  • <record-id> See Concepts: RecordID
  • <fetchPlan> Optional, is the fetch plan used. 0 means the root record, -1 infinite depth, positive numbers is the depth level. Look at Fetching Strategies for more information.

Example

HTTP GET request: http://localhost:2480/document/demo/9:0

HTTP response returns a single document, such as:

    {
      "_id": "9:0", 
      "_ver": 2, 
      "@class": "Profile", 
      "nick": "GGaribaldi", 
      "followings": [], 
      "followers": [], 
      "name": "Giuseppe", 
      "surname": "Garibaldi", 
      "location": "11:0", 
      "invitedBy": null, 
      "sex": "male", 
      "online": true
    }

The example above can be extended to return all the edges and vertices beneath #9:0

HTTP GET request: http://localhost:2480/document/demo/9:0/*:-1

POST - Document

Create a new document. Returns the RecordID assigned.

Syntax: http://<server>:[<port>]/document/<database>/<record-id>

Example

HTTP POST request: http://localhost:2480/document/demo

    content: 
    {
      "@class": "Profile", 
      "nick": "GGaribaldi", 
      "followings": [], 
      "followers": [], 
      "name": "Giuseppe", 
      "surname": "Garibaldi", 
      "location": "11:0", 
      "invitedBy": null, 
      "sex": "male", 
      "online": true
    }

HTTP response: 9:11

PUT - Document

Update a document. Remember to always pass the version to update. This prevent to update documents changed by other users (MVCC).

Syntax: http://<server>:[<port>]/document/<database>/<record-id>

Example

HTTP PUT request: http://localhost:2480/document/demo/9:0

    content: 
    {
      "@class": "Profile", 
      "@version": 3, 
      "nick": "GGaribaldi", 
      "followings": [], 
      "followers": [], 
      "name": "Giuseppe", 
      "surname": "Garibaldi", 
      "location": "11:0", 
      "invitedBy": null, 
      "sex": "male", 
      "online": true
    }

HTTP response: empty

DELETE - Document

Delete a document.

Syntax: http://<server>:[<port>]/document/<database>/<record-id>

Example

HTTP GET request: http://localhost:2480/document/demo/9:0

HTTP response: empty

Document By Class

GET Document by Class

Retrieve a document by cluster name and record position.

Syntax: http://<server>:[<port>]/documentbyclass/<database>/<class-name>/<record-position>[/fetchPlan]

Where:

  • <fetchPlan> Optional, is the fetch plan used. 0 means the root record, -1 infinite depth, positive numbers is the depth level. Look at Fetching Strategies for more information.

Example

HTTP GET request: http://localhost:2480/document/demo/Profile/0

HTTP response:

    {
      "_id": "9:0", 
      "_ver": 2, 
      "@class": "Profile", 
      "nick": "GGaribaldi", 
      "followings": [], 
      "followers": [], 
      "name": "Giuseppe", 
      "surname": "Garibaldi", 
      "location": "11:0", 
      "invitedBy": null, 
      "sex": "male", 
      "online": true
    }

Allocation

GET - Allocation

Retrieve information about the storage space of a disk-based database.

Syntax: http://<server>:[<port>]/allocation/<database>

Example

HTTP GET request: http://localhost:2480/allocation/demo

HTTP response: { "size": 61910, "segments": [ {"type": "d", "offset": 0, "size": 33154}, {"type": "h", "offset": 33154, "size": 4859}, {"type": "h", "offset": 3420, "size": 9392}, {"type": "d", "offset": 12812, "size": 49098} ], "dataSize": 47659, "dataSizePercent": 76, "holesSize": 14251, "holesSizePercent": 24 }

Index

NOTE: Every single new database has the default manual index called "dictionary".

GET - Index

Retrieve a record looking into the index.

Syntax: http://<server>:[<port>]/index/<index-name>/<key>

Example

HTTP GET request: http://localhost:2480/dictionary/test HTTP response:

    {
      "name" : "Jay",
      "surname" : "Miner"
    }

PUT - Index

Create or modify an index entry.

Syntax: http://<server>:[<port>]/index/<index-name>/<key>

Example

HTTP PUT request: http://localhost:2480/dictionary/test content: { "name" : "Jay", "surname" : "Miner" }

HTTP response: No response.

DELETE - Index

Remove an index entry.

Syntax: http://<server>:[<port>]/index/<index-name>/<key>

Example

HTTP DELETE request: http://localhost:2480/dictionary/test HTTP response: No response.

## Query ##

GET - Query

Execute a query against the database. Query means only idempotent commands like SQL SELECT and TRAVERSE. Idempotent means the command is read-only and can't change the database. Remember that in IE6 the URL can be maximum of 2,083 characters. Other browsers supports major length, but if you want to stay compatible with all limit to 2,083 characters.

Syntax: http://<server>:[<port>]/query/<database>/<language>/<query-text>[/<limit>][/<fetchPlan>]

Where:

  • <language> is the name of the language between those supported. OrientDB distribution comes with "sql" and GraphDB distribution has both "sql" and "gremlin"
  • query-text is the text containing the query to execute
  • limit is the maximum number of record to return. Optional, default is 20
  • fetchPlan is the fetching strategy to use. For more information look at Fetching Strategies. Optional, default is *:1 (1 depth level only)

Other key points:

Example

HTTP GET request: http://localhost:2480/query/demo/sql/select from Profile

HTTP response:

    { "result": [
    {
      "_id": "-3:1", 
      "_ver": 0, 
      "@class": "Address", 
      "type": "Residence", 
      "street": "Piazza di Spagna", 
      "city": "-4:0"
    },
    {
      "_id": "-3:2", 
      "_ver": 0, 
      "@class": "Address", 
      "type": "Residence", 
      "street": "test", 
      "city": "-4:1"
    }] }

The same query with the limit to maximum 20 results using the fetch plan *:-1 that means load all recursively:

HTTP GET request: http://localhost:2480/query/demo/sql/select from Profile/20/*:-1

Server

GET - Server

Retrieve information about the connected OrientDB Server. Requires additional authentication to the server.

Syntax: http://<server>:[<port>]/server

Example

HTTP GET request: http://localhost:2480/server HTTP response:

    {
      "connections": [{
        "id": "4", 
        "id": "4", 
        "remoteAddress": "0:0:0:0:0:0:0:1:52504", 
        "db": "-", 
        "user": "-", 
        "protocol": "HTTP-DB", 
        "totalRequests": "1", 
        "commandInfo": "Server status", 
        "commandDetail": "-", 
        "lastCommandOn": "2010-05-26 05:08:58", 
        "lastCommandInfo": "-", 
        "lastCommandDetail": "-", 
        "lastExecutionTime": "0", 
        "totalWorkingTime": "0", 
    ...
Clone this wiki locally