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.
allocation DB's defragmentation |
batch Batch of commands |
class Operations on schema classes |
cluster Operations on clusters |
command Executes commands |
connect Create the session |
database Information about database |
disconnect Disconnect session |
document Operations on documents by RID GET - HEAD - POST - PUT - DELETE |
documentbyclass Operations on documents by Class |
export Exports a database |
function Executes a server-side function |
index Operations on indexes |
listDatabases Available databases |
property Operations on schema properties |
query Query |
server Information about the server |
This protocol uses the four methods of the HTTP protocol:
When using POST and PUT the following are important when preparing the contents of the post message:
The REST API is very flexible, with the following features:
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:
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.
On first call (or when the session is expired and a new authentication is required), OrientDB returns the OSESSIONID parameter in response's HTTP header. On further calls the client should pass this OSESSIONID header in the requests and OrientDB will skip the authentication because a session is alive. By default sessions expire after 300 seconds (5 minutes), but you can change this configuration by setting the global setting: network.http.sessionExpireTimeout
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:
Connect to a remote server using basic authentication.
Syntax: http://<server>:[<port>]/connect/<database>
HTTP GET request: http://localhost:2480/connect/demo
HTTP response: 204 if ok, otherwise 401.
HTTP GET request: http://localhost:2480/database/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},
...
Gets informations about requested class.
Syntax: http://<server>:[<port>]/class/<database>/<class-name>
HTTP response:
{ "class": {
"name": "<class-name>"
"properties": [
{ "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
HTTP GET request: http://localhost:2480/class/demo/OFunction
HTTP response:
{
"name": "OFunction",
"superClass": "",
"alias": null,
"abstract": false,
"strictmode": false,
"clusters": [
7
],
"defaultCluster": 7,
"records": 0,
"properties": [
{
"name": "language",
"type": "STRING",
"mandatory": false,
"readonly": false,
"notNull": false,
"min": null,
"max": null,
"collate": "default"
},
{
"name": "name",
"type": "STRING",
"mandatory": false,
"readonly": false,
"notNull": false,
"min": null,
"max": null,
"collate": "default"
},
{
"name": "idempotent",
"type": "BOOLEAN",
"mandatory": false,
"readonly": false,
"notNull": false,
"min": null,
"max": null,
"collate": "default"
},
{
"name": "code",
"type": "STRING",
"mandatory": false,
"readonly": false,
"notNull": false,
"min": null,
"max": null,
"collate": "default"
},
{
"name": "parameters",
"linkedType": "STRING",
"type": "EMBEDDEDLIST",
"mandatory": false,
"readonly": false,
"notNull": false,
"min": null,
"max": null,
"collate": "default"
}
]
}
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
Create one or more properties into a given class. Returns the number of properties of the class.
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.
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>"
}
}
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
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://<server>:[<port>]/cluster/<database>/<cluster-name>/
Where <limit>
is optional and tells the maximum of records to load. Default is 20.
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"
}
...
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 executelimit
is the maximum number of record to return. Optional, default is 20fetchPlan
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.
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
Executes a batch of operations in a single call. This is useful to reduce network latency issuing multiple commands as multiple requests. Batch command supports transactions as well.
Syntax: http://<server>:[<port>]/batch/<database>
Content: { "transaction" :
Returns: Number of operations executed.
Where: type can be:
{ "transaction" : true,
"operations" : [
{ "type" : "u",
"record" : {
"@rid" : "#14:122",
"name" : "Luca",
"vehicle" : "Car"
}
}, {
"type" : "d",
"record" : {
"@rid" : "#14:100"
}
}, {
"type" : "c",
"record" : {
"@class" : "City",
"name" : "Venice"
}
}, {
"type" : "cmd",
"language" : "sql",
"command" : "create edge Friend from #10:33 to #11:33"
}, {
"type" : "script",
"language" : "javascript",
"script" : "orient.getGraph().createVertex('class:Account')"
}
]
}
{ "transaction" : true,
"operations" : [
{
"type" : "script",
"language" : "sql",
"script" : [ "let account = create vertex Account set name = 'Luke'",
"let city =select from City where name = 'London'",
"create edge Lives from $account to $city retry 100" ]
}
]
}
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://<server>:[<port>]/function/<database>/<name>[/<argument>*]<server>
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.
HTTP POST request: http://localhost:2480/function/demo/sum/3/5
HTTP response: 8.0
Retrieve all the information about a database.
Syntax: http://<server>:[<port>]/database/<database>
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},
{
...
Create a new database. Requires additional authentication to the server.
Syntax for the url `http://
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},
{
...
Drop a database. Requires additional authentication to the server.
Syntax: http://<server>:[<port>]/database/<databaseName>
Where:
HTTP DELETE request: http://localhost:2480/database/demo2
HTTP response code 204
Exports a gzip file that contains the database JSON export.
Syntax: http://
HTTP GET request: http://localhost:2480/export/demo2
HTTP response: demo2.gzip file
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
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"
}
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
HTTP GET request: http://localhost:2480/listDatabases
HTTP response:
{
"@type": "d", "@version": 0,
"databases": ["demo", "temp"]
}
Syntax: http://<server>:[<port>]/disconnect
HTTP GET request: http://localhost:2480/disconnect
HTTP response: empty.
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.HTTP GET request: http://localhost:2480/document/demo/9:0
HTTP response can be:
{
"_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
Check if a document exists
Syntax: http://<server>:[<port>]/document/<database>/<record-id>
Where:
<record-id>
See Concepts: RecordIDHTTP HEAD request: http://localhost:2480/document/demo/9:0
HTTP response can be:
Create a new document. Returns the document with the new @rid assigned. Before 1.4.x the return was the @rid content only.
Syntax: http://<server>:[<port>]/document/<database>
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, as the document created with the assigned RecordID as @rid:
{
"@rid": "#11:4456",
"@class": "Profile",
"nick": "GGaribaldi",
"followings": [],
"followers": [],
"name": "Giuseppe",
"surname": "Garibaldi",
"location": "11:0",
"invitedBy": null,
"sex": "male",
"online": true
}
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>][?updateMode=full|partial]
Where:
HTTP PUT request: http://localhost:2480/document/demo/9:0
content:
{
"@class": "Profile",
"@version": 3,
"nick": "GGaribaldi",
"followings": [],
"followers": [],
"name": "Giuseppe",
"online": true
}
HTTP response, as the updated document with the updated @version field (Since v1.6):
content:
{
"@class": "Profile",
"@version": 4,
"nick": "GGaribaldi",
"followings": [],
"followers": [],
"name": "Giuseppe",
"online": true
}
Delete a document.
Syntax: http://<server>:[<port>]/document/<database>/<record-id>
HTTP GET request: http://localhost:2480/document/demo/9:0
HTTP response: empty
Retrieve a document by cluster name and record position.
Syntax: http://<server>:[<port>]/documentbyclass/<database>/<class-name>/<record-position>[/fetchPlan]
Where:
<class-name>
is the name of the document's class<record-position>
is the absolute position of the record inside the class' default cluster<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.HTTP GET request: http://localhost:2480/documentbyclass/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
}
Check if a document exists
Syntax: http://<server>:[<port>]/documentbyclass/<database>/<class-name>/<record-position>
Where:
<class-name>
is the name of the document's class<record-position>
is the absolute position of the record inside the class' default clusterHTTP HEAD request: http://localhost:2480/documentbyclass/demo/Profile/0
HTTP response can be:
Retrieve information about the storage space of a disk-based database.
Syntax: http://<server>:[<port>]/allocation/<database>
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
}
NOTE: Every single new database has the default manual index called "dictionary".
Retrieve a record looking into the index.
Syntax: http://<server>:[<port>]/index/<index-name>/<key>
HTTP GET request: http://localhost:2480/dictionary/test
HTTP response:
{
"name" : "Jay",
"surname" : "Miner"
}
Create or modify an index entry.
Syntax: http://<server>:[<port>]/index/<index-name>/<key>
HTTP PUT request: http://localhost:2480/dictionary/test
content:
{
"name" : "Jay",
"surname" : "Miner"
}
HTTP response: No response.
Remove an index entry.
Syntax: http://<server>:[<port>]/index/<index-name>/<key>
HTTP DELETE request: http://localhost:2480/dictionary/test
HTTP response: No response.
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" only. Gremlin language cannot be executed with query because it cannot guarantee to be idempotent. To execute Gremlin use command instead.query-text
is the text containing the query to executelimit
is the maximum number of record to return. Optional, default is 20fetchPlan
is the fetching strategy to use. For more information look at Fetching Strategies. Optional, default is *:1 (1 depth level only)Other key points:
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
Retrieve information about the connected OrientDB Server. Requires additional authentication to the server.
Syntax: http://<server>:[<port>]/server
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",
...
Syntax: http://<server>:[<port>]/connection/<command>/<id>
Where:
You've to execute this command authenticated in the OrientDB Server realm (no database realm), so get the root password from config/orientdb-server-config.xml file (last section).