From bdacb5c25ae0f5d855fe85f1b2f0d619ae549026 Mon Sep 17 00:00:00 2001 From: ernado Date: Wed, 23 Jul 2014 16:10:27 +0400 Subject: [PATCH] added http api docs --- docs/api.rst | 303 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 304 insertions(+) create mode 100644 docs/api.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..62ed5b942 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,303 @@ +API +=================================== + +Master +################################### +You can append to any HTTP API with &pretty=y to see a formatted json output. + +Assign a file key +*********************************** + +.. code-block:: bash + + # Basic Usage: + curl http://localhost:9333/dir/assign + {"count":1,"fid":"3,01637037d6","url":"127.0.0.1:8080", + "publicUrl":"localhost:8080"} + # To assign with a specific replication type: + curl "http://localhost:9333/dir/assign?replication=001" + # To specify how many file ids to reserve + curl "http://localhost:9333/dir/assign?count=5" + # To assign a specific data center + curl "http://localhost:9333/dir/assign?dataCenter=dc1" + +Lookup volume +*********************************** +We would need to find out whether the volumes have moved. + +.. code-block:: bash + + curl "http://localhost:9333/dir/lookup?volumeId=3&pretty=y" + { + "locations": [ + { + "publicUrl": "localhost:8080", + "url": "localhost:8080" + } + ] + } + # Other usages: + # You can actually use the file id to lookup + curl "http://localhost:9333/dir/lookup?volumeId=3,01637037d6" + # If you know the collection, specify it since it will be a little faster + curl "http://localhost:9333/dir/lookup?volumeId=3&collection=turbo" + +Force garbage collection +*********************************** +If your system has many deletions, the deleted file's disk space will not be synchronously re-claimed. There is a background job to check volume disk usage. If empty space is more than the threshold, default to 0.3, the vacuum job will make the volume readonly, create a new volume with only existing files, and switch on the new volume. If you are impatient or doing some testing, vacuum the unused spaces this way. + +.. code-block:: bash + + curl "http://localhost:9333/vol/vacuum" + curl "http://localhost:9333/vol/vacuum?garbageThreshold=0.4" + +The garbageThreshold=0.4 is optional, and will not change the default threshold. You can start volume master with a different default garbageThreshold. + +Pre-Allocate Volumes +*********************************** + +One volume servers one write a time. If you need to increase concurrency, you can pre-allocate lots of volumes. + +.. code-block:: bash + + curl "http://localhost:9333/vol/grow?replication=000&count=4" + {"count":4} + # specify a collection + curl "http://localhost:9333/vol/grow?collection=turbo&count=4" + # specify data center + curl "http://localhost:9333/vol/grow?dataCenter=dc1&count=4" + +This generates 4 empty volumes. + +Upload File Directly +*********************************** + +.. code-block:: bash + + curl -F file=@/home/chris/myphoto.jpg http://localhost:9333/submit + {"fid":"3,01fbe0dc6f1f38","fileName":"myphoto.jpg", + "fileUrl":"localhost:8080/3,01fbe0dc6f1f38","size":68231} + +This API is a little convenient. The master server would contact itself via HTTP to get an file id and store it to the right volume server. It is a convenient API and does not support different parameters when assigning file id. + +Check System Status +*********************************** + +.. code-block:: bash + + curl "http://10.0.2.15:9333/cluster/status?pretty=y" + { + "IsLeader": true, + "Leader": "10.0.2.15:9333", + "Peers": [ + "10.0.2.15:9334", + "10.0.2.15:9335" + ] + } + curl "http://localhost:9333/dir/status?pretty=y" + { + "Topology": { + "DataCenters": [ + { + "Free": 3, + "Id": "dc1", + "Max": 7, + "Racks": [ + { + "DataNodes": [ + { + "Free": 3, + "Max": 7, + "PublicUrl": "localhost:8080", + "Url": "localhost:8080", + "Volumes": 4 + } + ], + "Free": 3, + "Id": "DefaultRack", + "Max": 7 + } + ] + }, + { + "Free": 21, + "Id": "dc3", + "Max": 21, + "Racks": [ + { + "DataNodes": [ + { + "Free": 7, + "Max": 7, + "PublicUrl": "localhost:8081", + "Url": "localhost:8081", + "Volumes": 0 + } + ], + "Free": 7, + "Id": "rack1", + "Max": 7 + }, + { + "DataNodes": [ + { + "Free": 7, + "Max": 7, + "PublicUrl": "localhost:8082", + "Url": "localhost:8082", + "Volumes": 0 + }, + { + "Free": 7, + "Max": 7, + "PublicUrl": "localhost:8083", + "Url": "localhost:8083", + "Volumes": 0 + } + ], + "Free": 14, + "Id": "DefaultRack", + "Max": 14 + } + ] + } + ], + "Free": 24, + "Max": 28, + "layouts": [ + { + "collection": "", + "replication": "000", + "writables": [ + 1, + 2, + 3, + 4 + ] + } + ] + }, + "Version": "0.47" + } + +Volume Server +################################### + +Upload File +*********************************** + +.. code-block:: bash + + curl -F file=@/home/chris/myphoto.jpg http://127.0.0.1:8080/3,01637037d6 + {"size": 43234} + +The size returned is the size stored on WeedFS, sometimes the file is automatically gzipped based on the mime type. + +Upload File Directly +*********************************** + +.. code-block:: bash + + curl -F file=@/home/chris/myphoto.jpg http://localhost:8080/submit + {"fid":"3,01fbe0dc6f1f38","fileName":"myphoto.jpg","fileUrl":"localhost:8080/3,01fbe0dc6f1f38","size":68231} + +This API is a little convenient. The volume server would contact the master to get an file id and store it to the right volume server(not necessarily itself). + +Delete File +*********************************** + +.. code-block:: bash + + curl -X DELETE http://127.0.0.1:8080/3,01637037d6 + +Create а specific volume on a specific volume server +***************************************************** +.. code-block:: bash + + curl "http://localhost:8080/admin/assign_volume?replication=000&volume=3" + +This generates volume 3 on this volume server. + +If you use other replicationType, e.g. 001, you would need to do the same on other volume servers to create the mirroring volumes. + +Check Volume Server Status +*********************************** + +.. code-block:: bash + + curl "http://localhost:8080/status?pretty=y" + { + "Version": "0.34", + "Volumes": [ + { + "Id": 1, + "Size": 1319688, + "RepType": "000", + "Version": 2, + "FileCount": 276, + "DeleteCount": 0, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 2, + "Size": 1040962, + "RepType": "000", + "Version": 2, + "FileCount": 291, + "DeleteCount": 0, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 3, + "Size": 1486334, + "RepType": "000", + "Version": 2, + "FileCount": 301, + "DeleteCount": 2, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 4, + "Size": 8953592, + "RepType": "000", + "Version": 2, + "FileCount": 320, + "DeleteCount": 2, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 5, + "Size": 70815851, + "RepType": "000", + "Version": 2, + "FileCount": 309, + "DeleteCount": 1, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 6, + "Size": 1483131, + "RepType": "000", + "Version": 2, + "FileCount": 301, + "DeleteCount": 1, + "DeletedByteCount": 0, + "ReadOnly": false + }, + { + "Id": 7, + "Size": 46797832, + "RepType": "000", + "Version": 2, + "FileCount": 292, + "DeleteCount": 0, + "DeletedByteCount": 0, + "ReadOnly": false + } + ] + } \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 561a79d7d..8dc87e8cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ Contents: gettingstarted clients + api Indices and tables