HTTP API Reference

Search…
HTTP API Reference
API definitions for terminusdb.
General rule
The TerminusDB Server HTTP API JSON documents have optional elements notated with angle-brackets, for instance:
1
{
2
  <"optional" : "foo">,
3
  "required" : "bar"
4
}
Copied!
​
Connect
1
GET http://localhost:6363/api/
Copied!
The Connect API endpoint returns the system:User object associated with the authentication provided. If no authentication is provided, the user will be the predefined terminusdb:///system/data/anonymous user.
Create Database
1
POST http://localhost:6363/api/db/<organization>/<dbid>
Copied!
The post argument is a JSON document of the following form:
1
{
2
   < "prefixes" : { < "@base" : Base_Prefix >,
3
                   < "@schema" : Schema_Prefix > } >
4
  "label" : "A Label",
5
  "comment" : "A Comment",
6
  < "public" : Boolean >,
7
  < "schema" : Boolean >
8
}
Copied!
Creates a new database with database ID dbid for organization organization.
The default prefixes associated with the document and the schema can be specified.
label: display name of thre database
comment: database description
label and comment are required fields.
The public boolean will determine if this database has read visibility to the anonymous user. It defaults to false.
The schema boolean will determine if this database is created with an empty schema, or if it is running in "schema free" mode. It defaults to false.
Example:
Create a database with the following: organization: admin dbid: cowid label: label comment "information about cows"
The payload in this case is:
1
{
2
  "prefixes": {"@base": "base_prefix",
3
             "@schema": "schema_prefix"},
4
  "comment" : "information about cows",
5
  "label" : "cow label"
6
}
Copied!
Delete Database
1
DELETE http://localhost:6363/api/db/<organization>/<dbid>
Copied!
The delete argument is a JSON document of the following form:
1
{ < "force" : Boolean >
2
}
Copied!
Add User to Organization
1
POST http://localhost:6363/api/organization
Copied!
The post argument is a JSON document of the following form:
1
{ "organization_name" : Organization_Name,
2
  "user_name" : User_Name }
Copied!
This endpoint will add the user User_Name to the organization Organization_Name.
Delete Organization
1
DELETE http://localhost:6363/api/organization
Copied!
The delete argument is a JSON document of the following form:
1
{ "organization_name" : Organization_Name }
Copied!
This endpoint will delete the organization Organization_Name.
Update Organization Name
1
POST http://localhost:6363/api/organization/<organization_name>
Copied!
The JSON API post parameter is:
1
{ "organization_name" : New_Name }
Copied!
This endpoint will update the name of the organization in the path to New_Name.
Add User
1
POST http://localhost:6363/api/user
Copied!
The JSON API post parameter is:
1
{ "user_identifier" : User_ID,
2
  "agent_name" : Agent_Name,
3
  "comment" : Comment,
4
  <"password" : Password>
5
}
Copied!
This endpoint adds the user User_ID and an organization of the same name to which the user will automatically be added, along with an optional password.
Delete User
1
DELETE http://localhost:6363/api/user/<user_name>
Copied!
This deletes the user named user_name.
Update User
1
POST http://localhost:6363/api/user/<user_name>
Copied!
The JSON API post parameter is:
1
{ <"user_identifier" : User_ID>,
2
  <"agent_name" : Agent_Name>,
3
  <"comment" : Comment>,
4
  <"password" : Passord>
5
}
Copied!
This endpoint allows a user to be updated with any of the supplied information in the JSON document.
Get Roles
1
GET http://localhost:6363/api/role
Copied!
The JSON API get parameter is:
1
{ <"agent_name" : Agent_Name >,
2
  <"database_name" : Database_Name >,
3
  <"organisation_name" : Organization_Name >
4
}
Copied!
This returns all roles in the system which match the passed parameters.
Update Roles
1
POST http://localhost:6363/api/update_role
Copied!
The JSON API post parameter is:
1
{ "agent_names" : Agents,
2
  "organization_name" : Organization,
3
  "actions" : Actions,
4
  <"database_name" : Database_Name >
5
}
Copied!
This endpoint will update the roles in the database with the associated list of actions for the named agents.
Clone
1
POST http://localhost:6363/api/clone/<organization>/[<new_dbid>]
Copied!
The JSON payload is:
1
{
2
   "comment" : Comment,
3
   "label" : Label,
4
   "remote_url" : Remote,
5
   < "public" : Bool >
6
}
Copied!
The API call creates a new database under the same DB ID as the cloned database, or with the new database ID new_dbid if provided.
The other options are exactly as with create db.
Example:
Clone the database admin/cowid.
1
POST http://localhost:6363/api/clone/admin/cowid
Copied!
JSON payload:
1
{
2
   "comment":"information about cows",
3
   "label" : "cow label"
4
   "remote_url" : "http://remoteurl/"
5
}
Copied!
Fetch
1
POST http://localhost:6363/api/fetch/<organization>/<dbid>
Copied!
Fetches new layers from the remotes for this database along with the commit history.
Rebase
1
POST http://localhost:6363/api/rebase/<organization>/<dbid>[/<repo>/branch/<branchid>]
Copied!
The JSON API document is:
1
{
2
   "rebase_from" : Resource,
3
   "author" : Author,
4
}
Copied!
The rebase_from contains an absolute string descriptor for the reference we are rebasing from. It may be a ref or a branch. Author should be the author of the newly produced commits.
This operation will attempt to construct a new history which has the same contents as that given by "rebase_from" by repeated application of diverging commits.
Example:
If the user wants to rebase the database admin/cowid, from branch_a to main, then the argument is:
1
POST "http://127.0.0.1:6363/api/rebase/admin/cowid/local/branch/main"
Copied!
and the payload is:
1
{
2
   "rebase_from" : "admin/cowid/local/branch/branch_a",
3
   "author" : "[email protected]",
4
​
5
}
Copied!
Push
1
POST http://localhost:6363/api/push/<organization>/<dbid>[/<repo>/branch/<branchid>/]
Copied!
The JSON API document is:
1
{ "remote" : Remote_Name,
2
  "remote_branch" : Remote_Branch,
3
  <"push_prefixes" : Boolean> }
Copied!
This endpoint pushes deltas from the branch specified in the path to the remote repository with the specified remote from the JSON object.
If "push_prefixes" is true, then it will also push the prefixes associated with the database to the remote.
Example:
Push the local branch branch_a to the branch main of the remote repository cow_information. Include the prefixes of the local database and update the prefixes of the remote.
1
POST http://localhost:6363/api/push/admin/cowid/local/branch/branch_a
Copied!
The JSON payload is:
1
{ "remote" : "cow_information",
2
  "remote_branch" : "main",
3
  "push_prefixes" : "True" }
Copied!
Pull
1
POST http://localhost:6363/api/pull/<organization>/<dbid>[/<repo>/branch/<branchid>/]
Copied!
JSON API document is:
1
{ "remote" : Remote_Name,
2
  "remote_branch" : Remote_Branch_Name
3
}
Copied!
Fetch layers from remote, then attempt a rebase from the remote branch remote_branch onto the local branch specified in the URL.
Example:
Fetch layers from remote repository: cow_information, branch main and rebase to the local branch branch_a
1
POST http://localhost:6363/api/pull/admin/cowid/local/branch/branch_a
Copied!
The JSON payload is:
1
{ "remote" : "cow_information",
2
  "remote_branch" : "main",
3
}
Copied!
Branch
1
POST http://localhost:6363/api/branch/<organization>/<dbid>/<repo>/<new_branchid>
Copied!
JSON API document is:
1
{ <"origin" : Remote_Name >
2
}
Copied!
Creates a new branch as specified by the URI, starting from the branch given by origin or empty if it is unspecified.
Example:
Create a new branch called branch_a from the remote repository cow_information, branch main
1
POST http://127.0.0.1:6363/api/branch/admin/cowid/local/branch_a
Copied!
JSON payload:
1
{ "origin" : "cow_information/main"
2
}
Copied!
Delete Branch
1
DELETE http://localhost:6363/api/branch/<organization>/<dbid>/<repo>/<branchid>
Copied!
Delete argument is a JSON document of the following form
1
{ < "force" : Boolean >
2
}
Copied!
Example:
Delete branch local/branch_a.
1
DELETE http://localhost:6363/api/branch/admin/cowid/local/branch_a
Copied!
Create Graph
1
POST http://localhost:6363/api/graph/<organization>/<dbid>/<repo>/branch/<branchid>/<instance|schema|inference>/<graphid>
Copied!
This takes a post parameter:
1
{"commit_info" : { "author" : Author, "message" : Message }}
Copied!
This API call creates a new graph as specified by the absolute graph descriptor in the URI.
Example:
Create a graph for admin/cowid
1
POST http://localhost:6363/api/graph/admin/cowid/local/main/
Copied!
JSON payload
1
{"commit_info" : { "author" : "[email protected]", "message" : "created a graph!" }}
Copied!
Delete Graph
1
DELETE http://localhost:6363/api/graph/<organization>/<dbid>/<repo>/branch/<branchid>/<instance|schema|inference>/<graphid>
Copied!
This takes the following parameter:
1
{"commit_info" : { "author" : Author, "message" : Message }}
Copied!
Deletes the graph specified by the absolute graph descriptor in the URI. If multiple graphs are created with different commits as above, the graphid needs to be specified.
Example:
delete the graph for: admin/cowid
1
DELETE http://localhost:6363/api/graph/admin/cowid/local/main/
Copied!
JSON payload
1
{"commit_info" : { "author" : "[email protected]", "message" : "deleted a graph!" }}
Copied!
Squash
1
POST http://localhost:6363/api/squash/<organization>/<dbid>/
Copied!
1
POST http://localhost:6363/api/squash/<organization>/<dbid>/local/branch/<branchid>
Copied!
This takes a post parameter:
1
{ "commit_info" : Commit_String }
Copied!
This API endpoint allows you to squashes a branch to a single commit. If the branch is left unspecified, it defaults to "local/main". The commit created can be attached to an arbitrary branch using ```reset`` (see below).
It returns a json object of the form
1
{ "@type":"api:SquashResponse",
2
  "api:commit": New_Commit_Path,
3
  "api:old_commit" : Old_Commit_Path,
4
  "api:status":"api:success"}
Copied!
This commit path can be used with reset, to add the commit to a specified branch as described above.
Example:
Squash branch local/main into a single commit.
1
POST http://127.0.0.1:6363/api/squash/admin/cowid/local/branch/main
Copied!
JSON payload:
1
{"commit_info" : { "author" : "[email protected]", "message" : "squashed_main" }}
Copied!
JSON return:
1
{ "@type":"api:SquashResponse",
2
  "api:commit": "local/main",
3
  "api:old_commit" : "local/main",
4
  "api:status":"api:success"}
Copied!
Reset
1
POST http://localhost:6363/api/reset/<organization>/<dbid>/
Copied!
1
POST http://localhost:6363/api/reset/<organization>/<dbid>/local/branch/<branchid>
Copied!
This takes a post parameter:
1
{ "commit_descriptor" : Ref }
Copied!
This API endpoint allows you to set a branch to an arbitrary commit. If the branch is left unspecified, it defaults to "local/main". The commit descriptor has to be a valid one, for example the return from squash above.
Example:
Set the brach local/main to the squashed commit specified above.
1
POST http://localhost:6363/api/reset/admin/cowid/local/main
Copied!
JSON payload:
1
{ "commit_descriptor" : { "@type":"api:SquashResponse",
2
                          "api:commit": "local/main",
3
                          "api:old_commit" : "local/main",
4
                          "api:status":"api:success"
5
                        }
6
}
Copied!
Get Triples
1
GET http://localhost:6363/api/triples/<organization>/<dbid>/<repo>/branch/<branchid>/<type>/<name><?format=turtle>
Copied!
1
GET http://localhost:6363/api/triples/<organization>/<dbid>/<repo>/commit/<refid>/<type>/<name><?format=turtle>
Copied!
This call returns a "Turtle" format file representation of the graph specified in the URL path as a JSON string. It takes a get parameter format which, if supplied, must always be "turtle". In the future we hope to support other formats.
Replace Triples
1
POST http://localhost:6363/api/triples/<organization>/<dbid>/local/branch/<branchid>/<type>/<name>
Copied!
Post argument is a JSON document of the following form
1
{ "turtle" : TTL_String,
2
  "commit_info" : { "author" : Author, "message" : Message } }
Copied!
This call creates the update required to make the graph referred to in the URL have exactly the triples specified in the turtle field of the JSON document. It must be supplied with a commit message (though it can be an empty string).
Update Triples
1
PUT http://localhost:6363/api/triples/<organization>/<dbid>/local/branch/<branchid>/<type>/<name>
Copied!
Put argument is a JSON document of the following form
1
{ "turtle" : TTL_String,
2
  "commit_info" : { "author" : Author, "message" : Message } }
Copied!
This call will simply add the passed triples from the "turtle" file to the graph specified.
Query
1
POST http://localhost:6363/api/woql
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>/_meta
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>/<repo>
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>/<repo>/_commits
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>/<repo>/branch/<branchid>
Copied!
1
POST http://localhost:6363/api/woql/<organization>/<dbid>/<repo>/commit/<refid>
Copied!
Post argument is a JSON document of the following form
1
{ <"commit_info" : { "author" : Author, "message" : Message } >,
2
  <"all_witnesses" : false >
3
  "query" : Query }
Copied!
The commit message is a requirement if an update is being made, whereas query should be a JSON-LD object.
If "all_witnesses" is false, then the end-point will return immediately when an schema violation is encountered with the first witness of failure.
This API call performs a WOQL query and returns an api:WoqlResponse result object, which has the form:
1
{ "@type" : "api:WoqlResponse",
2
  "api:status" : "api:success",
3
  "api:variable_names" : Variable_Names,
4
  "bindings" : Bindings,
5
  "inserts" : Number_Of_Inserts,
6
  "deletes" : Number_Of_Deletes,
7
  "transaction_retry_count" : Retries
8
  }
Copied!
Optimize
1
POST http://localhost:6363/api/optimize/_system
Copied!
1
POST http://localhost:6363/api/optimize/<organization>/<dbid>
Copied!
1
POST http://localhost:6363/api/optimize/<organization>/<dbid>/_meta
Copied!
1
POST http://localhost:6363/api/optimize/<organization>/<dbid>/<repo>/_commits
Copied!
1
POST http://localhost:6363/api/optimize/<organization>/<dbid>/<repo>/branch/<branch>
Copied!
This API endpoint will attempt to optimize the database using an appropriate strategy. This call is not recursive, i.e. it will only optimize access to the respective graph collection specified.
In the case of an unspecified branch, main is assumed.
Document Interface
Schema Reference
Last modified 4mo ago