Updated vault

radiokit · Apr 2, 2016 · 8a0e4bf · 8a0e4bf
1 parent 5611460
commit 8a0e4bf
Show file tree

Hide file tree

Showing 9 changed files with 148 additions and 23 deletions.
diff --git a/Makefile → docs/Makefile b/Makefile → docs/Makefile
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,37 +6,49 @@
 Welcome to RadioKit Engine's documentation!
 ===========================================
 
-RadioKit Engine is a cloud computing platform for building multimedia, mainly audio-oriented applications. You can think about it as of “Amazon Web Services for Audio”.
-
-Instead of building complicated infrastructure from scratch, you can take existing “building blocks” and build your app on top of them. Then RadioKit takes care about what’s hidden from the users, and you can focus on what is your core business and brings the most value to your users.
-
-Platform is API-oriented. That means that most of the functionality is available only through programming interfaces. There are some user interfaces for management, but they show only part of the potential.
-
-The API is mostly based on the REST API convention; so all communication with the system is done over HTTPS protocol, which is the most widely adopted Internet application protocol in the world. Data is serialized as JSON. That makes it effectively platform-independent, it does not matter what language or technology different parts of the system use, as they talk to each other with universal protocol.
-
-Our systems are built as micro services. There are several backends responsible for various tasks. Technically speaking they are separate applications (although still speaking with the same protocol). That allows us to keep system modular, create derivatives that fit specific clients’ needs, use different languages for different purposes and makes system more reliable as it is highly unlikely that all backends will go down at the same time.
-
-As most broadcasting applications have demand of high availability, we run our software only within credible, reliable datacentres and providers such as:
+RadioKit Engine is a cloud computing platform for building multimedia, mainly
+audio-oriented applications. You can think about it as of “Amazon Web Services
+for Audio”.
+
+Instead of building complicated infrastructure from scratch, you can take
+existing “building blocks” and build your app on top of them. Then RadioKit takes
+care about what’s hidden from the users, and you can focus on what is your core
+business and brings the most value to your users.
+
+Platform is API-oriented. That means that most of the functionality is available
+only through programming interfaces. There are some user interfaces for management,
+but they show only part of the potential.
+
+The API is mostly based on the REST API convention; so all communication with
+the system is done over HTTPS protocol, which is the most widely adopted Internet
+application protocol in the world. Data is serialized as JSON. That makes it
+effectively platform-independent, it does not matter what language or technology
+different parts of the system use, as they talk to each other with universal protocol.
+
+Pieces composing RadioKit Engine are built as micro services. There are several
+backends responsible for various tasks. Technically speaking they are separate
+applications (although still speaking with the same protocol). That allows us to
+keep system modular, create derivatives that fit specific clients’ needs, use different
+languages for different purposes and makes system more reliable.
+
+As most broadcasting applications have demand of high availability, we run our
+software only within credible, reliable datacentres and providers such as:
 
 *	Heroku (the biggest Platform-as-a-Service platform, itself hosted at Amazon Web Services),
 *	OVH (the biggest European datacentre),
 *	Microsoft Azure (cloud computing platform from Microsoft).
 
-We utilize worldwide Content Delivery Network CloudFlare which provides us geocaching (they have datacentres in India), speed optimization, encryption and protects the whole infrastructure from DDoS attacks.
+It is however, possible to host it within users' datacentre if certain technical
+requirements are met.
 
-All that means you don’t need to have your own infrastructure except applications that are specific to your business.
+We utilize worldwide Content Delivery Network CloudFlare which provides us geocaching,
+speed optimization, encryption and protects the whole infrastructure from DDoS attacks.
 
-
-Contents:
+Contents
+~~~~~~~~
 
 .. toctree::
    :maxdepth: 2
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   services
+   support
diff --git a/docs/source/services.rst b/docs/source/services.rst
@@ -0,0 +1,14 @@
+Services
+========
+
+
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   services/auth
+   services/plumber
+   services/vault
diff --git a/docs/source/services/auth.rst b/docs/source/services/auth.rst
@@ -0,0 +1,10 @@
+Auth (Authentication & Authorization provider)
+==============================================
+
+
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
diff --git a/docs/source/services/plumber.rst b/docs/source/services/plumber.rst
@@ -0,0 +1,10 @@
+Plumber (Live Audio Mixer)
+==========================
+
+
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
diff --git a/docs/source/services/vault.rst b/docs/source/services/vault.rst
@@ -0,0 +1,13 @@
+Vault (Repository of Media Files)
+=================================
+
+
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   vault/importing
+   vault/uploading
diff --git a/docs/source/services/vault/importing.rst b/docs/source/services/vault/importing.rst
@@ -0,0 +1,10 @@
+Importing
+=========
+
+TODO
+
+
+
+
+
+.. toctree::
diff --git a/docs/source/services/vault/uploading.rst b/docs/source/services/vault/uploading.rst
@@ -0,0 +1,47 @@
+Uploading
+=========
+
+There are several ways to upload media files into Vault. Depending on the context
+and desired integration with other applications you may want to push the whole
+file at once, ask service to pull it or upload it in chunks. Each of them has
+its benefits and drawbacks, described below.
+
+Please note that uploading refers to action initiated by user or another
+application. You also may want to take a look about importing features that
+can be used to automatically fetch content from existing applications without
+necessity to trigger such operation.
+
+Resumable.JS
+------------
+
+Vault provides interface for uploading via `Resumable.JS <http://resumablejs.com/>`_
+JavaScript library. This is the preferred way to import files through web browser.
+Resumable.JS provides ability to queue files, upload them in parallel, restart
+uploads and the most importantly, divide them into chunks. This is a quite reliable
+way to create uploader that handles large files even on weak network connections.
+
+The endpoint for uploading is https://vault.radiokitapp.org/api/upload/v1.0/resumablejs.
+Maximum chunk size is 4MB. You must pass some additional headers and parameters
+to the requests:
+
+* At least `Authorization` header (see: Authentication)
+* At least `record_repository_id` parameter (see: Repositories)
+
+Example using plain JavaScript
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    var r = new Resumable({
+      target: 'https://vault.radiokitapp.org/api/upload/v1.0/resumablejs',
+      query: {
+        radiokit: {
+          record_repository_id: '80332F34-F903-11E5-A3E1-3E19FDC8A409'
+        }
+    });
+
+    if(!r.support)  {
+      alert('Chunked upload is not supported, upgrade your web browser.');
+    }
+
+.. toctree::
diff --git a/docs/source/support.rst b/docs/source/support.rst
@@ -0,0 +1,9 @@
+Support
+=======
+
+If you need any support while developing services on top of the Engine and
+encounter any issues, our team of experts is ready to help.
+
+Don't hesitate to contact us at admin@radiokit.org
+
+.. toctree::