API for 'labelgraph' datatype (github.com/janelia-flyem/dvid/datatype/labelgraph) History and therefore UNDO is not yet supported. I will need to access the KeyValue setter and maintain a transaction log (how to avoid collisions with graph keyspacee if using the same key value store -- avoid conflict by doing a dynamic check?!). ============================================================================= HTTP API (Level 2 REST): Note: UUIDs referenced below are strings that may either be a unique prefix of a hexadecimal UUID string (e.g., 3FA22) or a branch leaf specification that adds a colon (":") followed by the case-dependent branch name. In the case of a branch leaf specification, the unique UUID prefix just identifies the repo of the branch, and the UUID referenced is really the leaf of the branch name. For example, if we have a DAG with root A -> B -> C where C is the current HEAD or leaf of the "master" (default) branch, then asking for "B:master" is the same as asking for "C". If we add another version so A -> B -> C -> D, then references to "B:master" now return the data from "D". Note that browsers support HTTP PUT and DELETE via javascript but only GET/POST are included in HTML specs. For ease of use in constructing clients, HTTP POST is used to create or modify resources in an idempotent fashion. GET /node///help Returns data-specific help message. GET /node///info POST /node///info Retrieves or puts data properties. Example: GET /node/3f8c/stuff/info Returns JSON with configuration settings. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of voxels data. GET /node///subgraph POST /node///subgraph DELETE /node///subgraph Performs graph-wide applications. Calling this will set a data-wide lock. If another subgraph call is performed during this operation, an error will be returned. Users should try making a request after a few hundred milliseconds. For now, there will be only one DVID client handling requests and it can probably handle a few hundred wait requests per second without many performance issues. GET (retrieve subgraph), POST (add subgraph -- does not change existing graph connections), DELETE (delete whole graph or subgraph indicated by a list of nodes or list of edges). POSTs or DELETEs using this URI will erase all merge history. Example: GET /node/3f8c/stuff/subgraph Returns the graph associated with the data "stuff" in version node 3f8c. An optional JSON can be specified listing the vertices to be included. The "Content-type" of the HTTP response are "application/json" as a node list and edge list. Vertex elements contain a "id" and "weight" (float). Edge elements contain "id1", "id2", and "weight" (float). When deleting or asking for a subgraph, specifying the vertex list will delete or retrieve the edges from these vertices. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. Query-string Options: unsafe Disable check of incoming JSON file (since schema verification is slow currently). Default false. POST /node///merge/[nohistory] Merge a list of vertices as specified by a vertex array called "vertices". The last vertex is the vertex ID that will be used. If nohistory is specified, the history of this transaction is not saved. Edge and Vertex weights will be summed. If different weights are desired, all edge and vertex weights should be specified as done when posting a subgraph. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. POST /node///undomerge Undoes last merge. An error message is returned if no UNDO occurs. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. GET /node///neighbors/ Retrieves the vertices/edges that are connected to the given vertex. The "Content-type" of the HTTP response are "application/json" as a node list and edge list. Vertex elements contain a "id" and "weight" (float). Edge elements contain "id1", "id2", and "weight" (float). Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. vertex ID of vertex POST /node///weight Updates the weight associated with the provided vertices and edges. Requests should be made in JSON following the graph schema. The weights provided represent the increment that should be applied to the weight for a vertex or edge. No more than 1000 vertices should be associated with these edges and vertices being updated. DVID guarantees the atomicity of this transaction by locking the vertices. If the vertex, doesn't exist it will be created. But an edge cannot be created unless one of its constituent vertices has been created (or is specified in this update call) Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. GET /node///propertytransaction// POST (really PUT) /node///propertytransaction// Retrieve or set the property given by for a set of vertices or edges. Both GET and POST requests must send binary data encoding the vertices that will need to be locked for this transaction. POST transactions should then list all the vertices and edges with the data to be posted. Only 1000 vertices can be locked for a given transaction. GET requests to non-existent properties will return a transaction id for the relevant vertices and empty data for the vertex/edge. The "Content-type" of the HTTP response and the request are "application/octet-stream" for arbitrary binary data. REQUEST BINARY FORMAT (all numbers are 8 byte unsigned numbers) array: array: RESPONSE BINARY FORMAT (all numbers are 8 byte unsigned numbers) array: array: array: Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. property Name of the property GET /node///property// POST (really PUT) /node///property// DELETE /node///property// Retrive or set a vertex property. The "Content-type" of the HTTP response and the request are "application/octet-stream" for arbitrary binary data. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. vertex ID of vertex key Name of the property GET /node///property/// POST (really PUT) /node///property/// DELETE /node///property/// Retrive or set an edge property. The "Content-type" of the HTTP response and the request are "application/octet-stream" for arbitrary binary data. Arguments: UUID Hexadecimal string with enough characters to uniquely identify a version node. data name Name of data to add/retrieve. vertex1 ID of vertex1 vertex2 ID of vertex2 key Name of the property TODO: * Bulk loading/retrieving (compression of JSON files) * Allow concurrent bulk reads * Handle tranactions across multiple DVID clients * Consider transaction/lock handling at a lower-level (Neo4j solutions?); atomicity of commands? * Implement transaction history as keyvalue array and support undo command (allow users to flush transaction history and perform mergers without transactions) * Implement better atomicity at storage level to prevent weirdness (all writes should be in a batch -- most currently are)