Skip to content
This repository has been archived by the owner on Sep 20, 2021. It is now read-only.

REST API

Jump to bottom
Chris Park edited this page May 15, 2020 · 42 revisions

Usage

Get (with curl or web browser)

Getting file/directory tag info is done with the GET method.

Curl example:
curl -X GET http://localhost:8000/api.php/indexname/endpoint

List all diskover indices with stats for each:
GET http://localhost:8000/api.php/list

List all files with no tag (untagged):
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag=&type=file

List all directories with no tag (untagged) and no custom tag:
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag=&tag_custom=&type=directory

List files with custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag_custom=version%201&type=file

List directories with custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag_custom=version%201&type=directory

List files/directories (all items) with custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag_custom=version%201

List files tagged archive:
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag=archive&type=file

List directories tagged delete:
GET http://localhost:8000/api.php/diskover-2018.01.17/tags?tag=delete&type=directory

List total size (in bytes) of files for each tag:
GET http://localhost:8000/api.php/diskover-2018.01.17/tagsize?type=file

List total size (in bytes) of files tagged delete:
GET http://localhost:8000/api.php/diskover-2018.01.17/tagsize?tag=delete&type=file

List total size (in bytes) of files with custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tagsize?tag_custom=version%201&type=file

List total number of files for each tag:
GET http://localhost:8000/api.php/diskover-2018.01.17/tagcount?type=file

List total number of files tagged delete:
GET http://localhost:8000/api.php/diskover-2018.01.17/tagcount?tag=delete&type=file

List total number of files with custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tagcount?tag_custom=version+1&type=file

List total number of files tagged keep and custom tag "version 1":
GET http://localhost:8000/api.php/diskover-2018.01.17/tagcount?tag=keep&tag_custom=version+1&type=file

List all duplicate files:
GET http://localhost:8000/api.php/diskover-2018.01.17/dupes

List total file size of duplicate files:
GET http://localhost:8000/api.php/diskover-2018.01.17/dupessize

Search index using ES query syntax:
GET http://localhost:8000/api.php/diskover-2018.01.17/search?query=extension:png%20AND%20_type:file%20AND%20filesize:>1048576

For "tags", "dupes" and "search" endpoints, you can set the page number and result size with ex. &page=1 and &size=100. Default is page 1 and size 1000.

Update (with JSON object)

Updating file/directory tags is done with the PUT method. You can send a JSON object in the body. The call returns the number of items affected.

Curl example:
curl -X PUT http://localhost:8000/api.php/index/endpoint -d '{}'

Tag files delete:
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagfile
{"tag": "delete", "files": ["/Users/shirosai/file1.png", "/Users/shirosai/file2.png"]}

Tag files delete and custom tag "version 1":
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagfile
{"tag": "delete", "tag_custom": "version 1", "files": ["/Users/shirosai/file1.png", "/Users/shirosai/file2.png"]}

Tag directory archive (non-recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag": "archive", "path_parent": "/Users/shirosai/Downloads"}

Tag directory and all files in directory with custom tag "version 1" (non-recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag_custom": "version 1", "path_parent": "/Users/shirosai/Downloads", "tagfiles": "true"}

Tag directory and all sub dirs (no files) with custom tag "version 1" (recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag_custom": "version 1", "path_parent": "/Users/shirosai/Downloads", "recursive": "true"}

Tag directory and all items (files/directories) in directory and all sub dirs with custom tag "version 1" (recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag_custom": "version 1", "path_parent": "/Users/shirosai/Downloads", "recursive": "true", "tagfiles": "true"}

Remove tag from directory and all files in directory (non-recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag": "", "path_parent": "/Users/shirosai/Downloads", "tagfiles": "true"}

Remove tag_custom from directory and all files in directory (non-recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag_custom": "", "path_parent": "/Users/shirosai/Downloads", "tagfiles": "true"}

Remove tag and tag_custom from directory and all items (files/directories) in directory and all sub dirs (recursive):
PUT http://localhost:8000/api.php/diskover-2018.01.17/tagdir
{"tag": "", "tag_custom": "", "path_parent": "/Users/shirosai/Downloads", "recursive": "true", "tagfiles": "true"}

diskover enterprise

diskover enterprise allows up to 3 custom tags, replace "tag_custom" with "tag_custom1", "tag_custom2", or "tag_custom3".

Also diskover enterprise uses "type" instead of "_type" field.

Curl

You may need to specify the header content type when using curl, for example:

curl -H 'Content-Type: application/json' -X PUT ...

Nginx

If you are using nginx, you may need to allow PUT request.

If you are getting timeouts and timeout errors in nginx logs, you may need to increase time limits.

If you are getting 404 on "list" or others, change nginx config for diskover-web server section

location ~ .php$ {

to

location ~ .php(/|$) {

PHP timeouts

If you are tagging a lot of files, you may get php timeouts, increase php max execution time.

Example usage in Python

"""example usage of diskover-web rest-api using requests and urllib
"""
import requests
try:
    from urllib import quote
except ImportError:
    from urllib.parse import quote
import json


url = "http://localhost:8000/api.php"

# list all diskover indices
r = requests.get('%s/list' % url)
print(r.url + "\n")
print(r.text + "\n")

# list total number of files for each tag in diskover-index index
index = "diskover-index"
r = requests.get('%s/%s/tagcount?type=file' % (url, index))
print(r.url + "\n")
print(r.text + "\n")

# list all png files in diskover-index index
q = quote("extension:png AND _type:file AND filesize:>1048576")
r = requests.get('%s/%s/search?query=%s' % (url, index, q))
print(r.url + "\n")
print(r.text + "\n")

# tag directory and all files in directory with tag "archive" (non-recursive)
d = {'tag': 'archive', 'path_parent': '/Users/cp/Downloads', 'tagfiles': 'true'}
r = requests.put('%s/%s/tagdir' % (url, index), data = json.dumps(d))
print(r.url + "\n")
print(r.text + "\n")
Clone this wiki locally