Skip to content
GitLab
Explore
Projects
Groups
Snippets
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
0Z090 5UR4l9V
Pod
Commits
a0f757aa
Unverified
Commit
a0f757aa
authored
4 years ago
by
Vasili Novikov
Browse files
Options
Download
Email Patches
Plain Diff
Document new API for review
parent
e7f80b11
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
README.md
+1
-1
README.md
docs/HTTP_API.md
+124
-57
docs/HTTP_API.md
with
125 additions
and
58 deletions
+125
-58
README.md
+
1
-
1
View file @
a0f757aa
...
...
@@ -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):
...
...
This diff is collapsed.
Click to expand it.
docs/HTTP_API.md
+
124
-
57
View file @
a0f757aa
...
...
@@ -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.
This diff is collapsed.
Click to expand it.
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment
Menu
Explore
Projects
Groups
Snippets