Broadcast channel & Rest API description enhanced

radiokit · Jul 21, 2016 · 239746f · 239746f
1 parent 7ea7502
commit 239746f
Show file tree

Hide file tree

Showing 6 changed files with 343 additions and 210 deletions.
diff --git a/docs/source/services.rst b/docs/source/services.rst
@@ -7,10 +7,9 @@ Services
 Contents:
 
 .. toctree::
-   :maxdepth: 2
 
    services/agenda
    services/auth
    services/plumber
-   services/restapi
+   services/rest
    services/vault
diff --git a/docs/source/services/agenda/channels.rst b/docs/source/services/agenda/channels.rst
@@ -1,15 +1,16 @@
 Broadcast Channel
 =================
 
-Broadcast.Channel is a model in Agenda microservice which gathers all
-data for a given audio channel.
+Broadcast.Channel is a model in Agenda microservice which is a kind of
+superior container for broadcast streams and contents.
 
-Broadcast channel records are accessible using `Official RadioKit REST Api <http://docs.radiokit.org/projects/engine/en/latest/services/restapi.html>`_.
+
+Broadcast channel records are accessible using `Official RadioKit REST Api`_.
 The following URL should be used to obtain Broadcast.Channel records:
 
 .. code-block:: rest
 
-    http://agenda.backend.url/api/rest/v1.0/broadcast/channel
+    https://agenda.backend.url/api/rest/v1.0/broadcast/channel
 
 
 Broadcast channel data
@@ -18,50 +19,122 @@ Broadcast channel data
 The following broadcast channel data fields are available for the user for index
 and show MVC action:
 
-+------------------------+--------------------------------------------------+
-| Field                  | Description                                      |
-+========================+==================================================+
-| id                     | Channel id                                       |
-+------------------------+--------------------------------------------------+
-| name                   | Name of the channel                              |
-+------------------------+--------------------------------------------------+
-| slug                   |                                                  |
-+------------------------+--------------------------------------------------+
-| timezone               | Timezone used for the channel                    |
-+------------------------+--------------------------------------------------+
-| description            | Channel's description                            |
-+------------------------+--------------------------------------------------+
-| media_routing_group_id |                                                  |
-+------------------------+--------------------------------------------------+
-| homepage_url           | Homepage's URL                                   |
-+------------------------+--------------------------------------------------+
-| genre                  | Channel's genre                                  |
-+------------------------+--------------------------------------------------+
-| references             |                                                  |
-+------------------------+--------------------------------------------------+
-| extra                  |                                                  |
-+------------------------+--------------------------------------------------+
-| inserted_at            | Date and time of the last udpate for the record  |
-+------------------------+--------------------------------------------------+
-| updated_at             | Date and time whien the record was created       |
-+------------------------+--------------------------------------------------+
-
-Condition Fields
-----------------
++------------------------+----------+--------------------------------------------------+
+| Field                  | Type     | Description                                      |
++========================+==========+==================================================+
+| id                     | UUID     | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+| name                   | string   | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+| slug                   | string   |                                                  |
++------------------------+----------+--------------------------------------------------+
+| timezone               | string   | Timezone used for the channel                    |
++------------------------+----------+--------------------------------------------------+
+| description            | string   | Channel's description                            |
++------------------------+----------+--------------------------------------------------+
+| media_routing_group_id | UUID     |                                                  |
++------------------------+----------+--------------------------------------------------+
+| homepage_url           | string   | Homepage's URL                                   |
++------------------------+----------+--------------------------------------------------+
+| genre                  | string   | Channel's genre                                  |
++------------------------+----------+--------------------------------------------------+
+| references             | map      | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+| extra                  | map      | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+| inserted_at            | DateTime | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+| updated_at             | DateTime | Refer to: `Model Common Fields`_.                |
++------------------------+----------+--------------------------------------------------+
+
+
+Fields That Can/Must Be Specified During Creation
+-------------------------------------------------
+
+During creation of the record user can specify values for some of the fields. Some
+of them are required for the creation of the record ad some of them are optional.
+Not specifying all the required fields for the creation of the record will result in
+request being rejected.
+
++------------------------+----------+----------+
+| Field                  | Type     | Required |
++========================+==========+==========+
+| name                   | string   | yes      |
++------------------------+----------+----------+
+| slug                   | string   | yes      |
++------------------------+----------+----------+
+| timezone               | string   | yes      |
++------------------------+----------+----------+
+| description            | string   | no       |
++------------------------+----------+----------+
+| media_routing_group_id | UUID     | yes      |
++------------------------+----------+----------+
+| homepage_url           | string   | no       |
++------------------------+----------+----------+
+| genre                  | string   | no       |
++------------------------+----------+----------+
+| references             | map      | no       |
++------------------------+----------+----------+
+| extra                  | map      | no       |
++------------------------+----------+----------+
+
+
+Fields That Can Be Updated After Creation
+-----------------------------------------
+
+There are some fields for which the value can be updated after the record is created.
+Crucial fields can be assigned a value only during creation and they cannot be
+changed later. The following fields can be updated by the user after record creation:
+
++------------------------+----------+
+| Field                  | Type     |
++========================+==========+
+| name                   | string   |
++------------------------+----------+
+| timezone               | string   |
++------------------------+----------+
+| description            | string   |
++------------------------+----------+
+| homepage_url           | string   |
++------------------------+----------+
+| genre                  | string   |
++------------------------+----------+
+| references             | map      |
++------------------------+----------+
+| extra                  | map      |
++------------------------+----------+
+
+
+Fields That Can Be Used in Conditions
+-------------------------------------
+
 The following broacast channel data fields can be used in conditions in
 index and show MVC actions:
 
-+------------------------+--------------------------------------------------+
-| Field                  | Description                                      |
-|                        |                                                  |
-+========================+==================================================+
-| name                   | Name of the channel                              |
-+------------------------+--------------------------------------------------+
-| slug                   |                                                  |
-+------------------------+--------------------------------------------------+
++------------------------+----------+
+| Field                  | Type     |
++========================+==========+
+| name                   | string   |
++------------------------+----------+
+| slug                   | string   |
++------------------------+----------+
+
+Other Records That Can Be Used for Join
+---------------------------------------
+
+The following records can be used for join operation in index and show MVC actions:
+
++------------------------+------------------------------+------------------------------+
+| Field                  | Model                        | Description                  |
++========================+==============================+==============================+
+| schedule_content_types | Agenda.Broadcast.ContentType | Content types that belong to |
+|                        |                              | broadcast channel            |
++------------------------+------------------------------+------------------------------+
+| broadcast_streams      | Agenda.Broadcast.Stream      | Broadcast streams that       |
+|                        |                              | belong to broadcast channel  |
++------------------------+------------------------------+------------------------------+
 
-Channel Broadcast Methods
--------------------------
-Model Brodacast.Channel does not provide any methods.
+.. _Official RadioKit REST Api: http://docs.radiokit.org/projects/engine/en/latest/services/restapi.html
+.. _Model Common Fields: http://docs.radiokit.org/projects/engine/en/latest/services/rest/common_fields.html
 
-.. toctree::
+.. toctree::
diff --git a/docs/source/services/rest.rst b/docs/source/services/rest.rst
@@ -0,0 +1,13 @@
+Official RadioKit REST API
+==========================
+
+
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   rest/restapi
+   rest/common_fields
diff --git a/docs/source/services/rest/common_fields.rst b/docs/source/services/rest/common_fields.rst
@@ -0,0 +1,28 @@
+Model Common Fields
+===================
+
+There is a number of fields that are common for all the models in all the RadioKit microservices.
+This chapter describes those fields in details.
+
++-------------+-------------+-----------------------------------------------------------+
+| Field       | Type        | Description                                               |
++=============+=============+===========================================================+
+| id          | UUID string | Unique identifier of each record.                         |
+|             |             |                                                           |
+|             |             | For more information about UUID type refer to             |
+|             |             | `Ecto.UUID <https://hexdocs.pm/ecto/Ecto.UUID.html>`_.    |
++-------------+-------------+-----------------------------------------------------------+
+| name        | string      | Name of record                                            |
++-------------+-------------+-----------------------------------------------------------+
+| references  | map         | ID of the record in another microservice. Used to express |
+|             |             | relation between records in different microservices       |
++-------------+-------------+-----------------------------------------------------------+
+| extra       | map         | Container used to store all data that do not fit to       |
+|             |             | predefined fields of the model                            |
++-------------+-------------+-----------------------------------------------------------+
+| inserted_at | DateTime    | Date and time of the last udpate for the record           |
++-------------+-------------+-----------------------------------------------------------+
+| updated_at  | DateTime    | Date and time when the record was created                 |
++-------------+-------------+-----------------------------------------------------------+
+
+.. toctree::