Merge branch 'master' of https://github.com/chrislusf/weed-fs

1 files changed, 303 insertions, 0 deletions

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 000000000..4f3806be9
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,303 @@
+API
+===================================
+
+Master server
+###################################
+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