-
Notifications
You must be signed in to change notification settings - Fork 0
OrientDB REST
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.
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
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
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.
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
Syntax: http://:[]/connect/
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},
...
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
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
}
}
}
}
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://:[
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 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.
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 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.
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://:
- 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.
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:
- databaseName is the name of database
HTTP DELETE request: http://localhost:2480/database/demo2
HTTP response code 204
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
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"]
}
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"
}
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 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
Create a new document. Returns the RecordID assigned.
Syntax: http://<server>:[<port>]/document/<database>/<record-id>
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
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>
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 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:
-
<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/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
}
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" 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:
- To use commands that change the database (non-idempotent), see the POST – Command section
- The command-text included in the URL must be encoded as per a normal URL
- See the SQL section, or the Gremlin introduction for the type of queries that can be sent
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",
...