RESTful API

NOTE

This article introduces the minimum procedure of using Ultipa RESTful API proxy.

Prerequisites

• a command line terminal that is compatible with your operating system:
  • Linux or MacOS: Bash, Zsh, TCSH
  • Windows: PowerShell
• a version of Ultipa RESTful API compatible with your operating system

Start API Service

1. Show help

Command
./ultipa_restful_api.exe --help

1. Show current version

Command
./ultipa_restful_api.exe --version

1. Start API service

Command
./ultipa_restful_api.exe --hosts 192.168.1.85:61095,192.168.1.87:61095,192.168.1.88:61095 -u employee -p joaGsdf -w 3

Note: -hosts, -u and -p are equivalent to --hosts, --username and --password

Other Parameters:

API Basic Info

• Request type: POST
• Request URL:
  • Linux: the Ultipa server that the current API service connects, e.g. 'http://192.168.1.88'
  • Windows/MacOS: the local address of the current API service, 'http://127.0.0.1'
• Request port: the valid ports set via -w and -l when starting the API service
• Body parameter type: JSON, FORM

Login Ultipa Service

• Request URL

URL
.../login

• Request Example

JSON
{
    "username": "employee",
    "password": "joaGsdf"
}

• Response: the token value after login

NOTE

The rest of API interfaces should all have this token value carried in Cookie in the Headers, ultipa=<token_value>, with Content_Type application/json.

Send UQL

• Request URL

URL
.../uql

• Request Parameter

• Request Example

JSON
{
    "uql": "find().nodes({name == \"abc\"}) return count(nodes)",
    "graph": "test_text"
}

• Success Response

JSON
{
    "Data": [
        {
            "Name": "count(nodes)",
            "PropertyType": 4,
            "Rows": [
                2
            ]
        }
    ],
    "Graph": "test_text",
    "Statistic": {
        "NodeAffected": 0,
        "EdgeAffected": 0,
        "TotalCost": 0,
        "EngineCost": 0
    },
    "Status": {
        "Message": "",
        "Code": 0
    }
}

Send UQL and limit returns

• Request URL

URL
.../uql/stream

• Request Parameter

• Request Example

JSON
{
    "uql": "find().nodes({name == \"abc\"}) return nodes",
    "graph": "test_text",
    "package_num": 1
}

• Success Response

Insert Nodes

• Request URL

URL
.../insert/nodes

• Request Parameter

• Request Example

JSON
{
    "nodes": [{"name":"Jason","_id":"USER001"},{"name":"Alice"}],
    "schema": "default",
    "graph": "test_text",
    "sync": true
}

• Success Response

JSON
{
    "Msg": "Insert Nodes Success: [{\"_id\":\"USER001\",\"name\":\"Jason\"},{\"name\":\"Alice\"}]"
}

Insert Edges

• Request URL

URL
.../insert/edges

• Request Parameter

• Request Example

JSON
{
    "edges": [{"year":"1998", "_from":"USER001", "_to":"USER002"}],
    "schema": "default",
    "graph": "test_text",
    "sync": true
}

• Success Response

JSON
{
    "Msg": "Insert Edges Success: [{\"_from\":\"USER001\",\"_to\":\"USER002\",\"year\":\"1998\"}]"
}

Update Nodes

Update nodes based on _id or _uuid.

• Request URL

URL
.../update/nodes

• Request Parameter

• Request Example

JSON
{
    "nodes": [{"age":"35", "_id":"USER001"}, {"name":"John", "_id": "USER002"}],
    "graph": "test_text"
}

• Success Response

JSON
{
    "Msg": "Update nodes on test_text",
    "SuccessCount": 2
}

Update Edges

Update edges based on _from&_to or _uuid.

• Request URL

URL
.../update/edges

• Request Parameter

• Request Example

JSON
{
    "edges": [{"_uuid":"1","_from_uuid":"2", "age":"55"}],
    "graph": "test_text"
}

• Success Response

JSON
{
    "Msg": "Update edges on test_text",
    "SuccessCount": 1
}