Unverified Commit a0f757aa authored by Vasili Novikov's avatar Vasili Novikov
Browse files

Document new API for review

parent e7f80b11
Showing with 125 additions and 58 deletions
+125 -58
......@@ -44,7 +44,7 @@ During development, you might want to have faster build turn-around.
Use this to incrementally compile the project (after installing [cargo-watch](https://github.com/passcod/cargo-watch)):
```sh
cargo watch
cargo watch --ignore /docs --ignore /data
```
To build (debug version):
......
......@@ -24,7 +24,7 @@ Set by the client by default.
* `dateModified`, last modification date _as seen by the client_. Set by the client by default.
* `deleted`, a flag that, if set to `true`, will mean that the item was deleted by the user.
It is still possible to restore the item later on.
Permanent delete will be supported in future, based in deletion date.
Permanent delete will be supported in the future, based in deletion date.
* `version`, a number that is incremented with each update from the client.
This field is fully controlled by the Pod, all input on it will be ignored and it will always
store the real number of updates that happened to an item.
......@@ -53,24 +53,62 @@ support properties in the future (don't rely on it yet).
# API
### Authentication & Credentials
Some endpoints require additional authentication / credentials.
In text below, `database_key` means a 64-character hex string to be used with sqlcipher.
It should be generated by the client once and kept there.
This key will never be written to disk by Pod, and is used to open the database.
You can read more on how this key is used in sqlcipher
[here](https://github.com/sqlcipher/sqlcipher).
In text below, `owner_key` means the full client-s public [ED25519](https://ed25519.cr.yp.to/) key
(see also [wikipedia](https://en.wikipedia.org/wiki/Curve25519)).
It should be encoded as 64-character hex string.
It is also used as authentication mechanism in the current version of Pod.
Pod wil calculate the hash of the `owner_key`,
and if it matches pre-defined values, will accept the request.
⚠️ UNSTABLE: The use of this key for authentication will be changed in the nearest future.
Note that incorrect database key (below) will also fail any request.
### GET /version
Get the version of the Pod. In future, it will also point to a specific git commit.
Get version of the Pod: the git commit and cargo version that it was built from.
### GET /v1/items/{uid}
Get a single item by it's `uid`.
### POST /v2/$owner_key/get_item/$uid
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Get a single item by its `uid`.
⚠️ UNSTABLE: currently, the endpoint returns an empty array if an item is not found,
or an array with 1 item if item exists.
In future, the endpoint might return an error if item was not found,
In the future, the endpoint might return an error if item was not found,
and the object itself if the item was found.
### GET /v1/all_items/
### POST /v2/$owner_key/all_items
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Get an array of all items.
### POST /v1/items/
### POST /v2/$owner_key/items/
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": { ... }
}
```
Create a single item.
* `uid` property MUST be present in input json
......@@ -80,11 +118,17 @@ Create a single item.
Returns `uid` of the created item. Returns an error if an `uid` did already exist.
⚠️ UNSTABLE: In future, the endpoint might allow creating items without `uid` being explicitly set,
⚠️ UNSTABLE: In the future, the endpoint might allow creating items without `uid` being explicitly set,
and just return the `uid` to the caller.
### PUT /v1/items/{uid}
### PUT /v2/$owner_key/items/$uid
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": { ... }
}
```
Update a single item.
* `uid` from the input json will be ignored
......@@ -97,84 +141,107 @@ and in fact will be increased by 1 from previous database value.
Returns an empty object if the operation is successful.
### POST /v1/bulk_action/
Perform a bulk of operations atomically.
Example input json:
### POST /v2/$owner_key/bulk_action/
```json
{
"createItems": [
{ /* structure identical to the create endpoint */ },
...
],
"updateItems": [
{ /* structure identical to the update endpoint */ },
...
],
"deleteItems": [ uid, uid, uid, ...],
"createEdges": [
{ "_source": uid, "_target": uid, "_type": "AnyString", /* other properties can be set */ },
...
],
/* Delete an edge and all its properties */
/* WARNING: Deleting is irreversible!!! */
"deleteEdges": [
{ "_source": uid, "_target": uid, "_type": "Some Type" },
...
],
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": {
"createItems": [
{ "uid": 12345, "_type": "Person", ... }, ...
],
"updateItems": [
{ "uid": 12345, ... }, ...
],
"deleteItems": [ uid, uid, uid, ...],
"createEdges": [
{ "_source": uid, "_target": uid, "_type": "AnyString", ... }, ...
],
"deleteEdges": [
{ "_source": uid, "_target": uid, "_type": "Some Type", ... }, ...
],
}
}
```
Perform a bulk of operations atomically.
If `createEdges` array is not empty, all items in `createItems` MUST have `uid` set.
Returns an empty object if the operation is successful.
### DELETE /v1/items/{uid}
Mark an item as deleted by:
* Setting `deleted` flag to `true`
* Updating `dateModified` (server-s time is taken)
### GET /v1/deprecated/uri_exists/{uri}
⚠️ DEPRECATED Check if an item exists with the `uri`.
Returns `true` successfully if such item exists,
or returns `false` successfully if such item does not exist.
### DELETE /v2/$owner_key/items/$uid
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Mark an item as deleted:
* Set `deleted` flag to `true`
* Update `dateModified` (server-s time is taken)
### POST /v1/search_by_fields/
Search items by their fields.
Given a json like
```
{ "_type": "Label", "color": "#CCFF00" }
### POST /v2/$owner_key/search_by_fields/
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": { "_type": "Label", "color": "#CCFF00" }
}
```
the endpoint will return an array of all items with exactly the same properties.
Search items by their fields.
The endpoint will return an array of all items with exactly the same properties.
### GET /v1/item_with_edges/{uid}
### POST /v2/$owner_key/get_item_with_edges/$uid
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
}
```
Get item, with edges of any type pointing from that item,
and all item's properties that those edges point to.
### POST /v1/items_with_edges
Given an input array of `uid`-s like
### POST /v2/$owner_key/items_with_edges
```json
[1, 20, 30, 100000]
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": [1, 20, 30, 100000]
}
```
for each `uid`, find the underlying item, all it's edges and all items that these edges point to.
Given an input array of `uid`-s, for each `uid`, find the underlying item,
all its edges and all items that these edges point to.
If at least one of the `uid`-s doesn't exist, return 404 NOT_FOUND for the whole request.
### POST /v1/run_service/downloaders/{service}/{data_type}
### POST /v2/$owner_key/run_service/downloaders/{service}/{data_type}
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Run a downloader for different services with different data types, e.g. Evernote with note.
Unsupported service or data type will yield 400 BAD_REQUEST error.
### POST /v1/run_service/importers/{data_type}
### POST /v2/$owner_key/run_service/importers/{data_type}
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Run an importer for a given data type, e.g. note.
Unsupported data type will yield 400 BAD_REQUEST error.
### POST /v1/run_service/indexers/{uid}
### POST /v2/$owner_key/run_service/indexers/$uid
```json
{
"database_key": "2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99",
"payload": null
}
```
Run an indexer on an item with the given uid.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment