# Blog Socket

## Intro

This is a try to define a Blog Socket in Syncano. Such socket gives a base functionalities that allows to
host and manage a blog in Syncano Platform. I've decided to make some simplifications - only two user roles:
`user` and `admin`; In popular blogging platforms there are more roles usually (editor, author, contributor).

## User stories

  * As an user I want to read blog post.
  * As an user I want to see main page with post wall.
  * As an user I want to make a comment under the post.
  * As an user I want to see comments list under the post made by other users.
  * As an user I want to login/register to write a comment.
  * As an user I want to give a like for post.
  * As an admin I want to be able to add blog post.
  * As an admin I want to be able to publish post (set status to publish).
  * As an admin I want to be able to schedule blog post (set as publish in a given time).
  * As an admin I want to be able to edit blog post.
  * As an admin I want to be able to remove blog post.
  * As an admin I want to be able to unpublish blog post.
  * As an admin I want to be able to manage my media library: add/edit/remove.
  * As a developer I want to have possibility to edit blog template.

## Classes

    class post
        id          an ID of the post (not editable)
        created_at  the creation date (not editable)
        updated_at  the last update date (not editable)
        created_by  by who this post was created (multiple admins) (not editable)
        updated_by  by who this post was updated (multiple admins) (not editable)
        title       the title of the post
        text        the body of the post
        image       the main image of the post (relation to `media` class)
        status      the main image of the post (relation to `media` class)

    class media
        id          the ID of the image (not editable)
        title       The media title
        media       the image URL
        size        image size (eg.: filtering by size when frontend expect a thumbnail)
        type        one of the: image|video|audio

    class comment
        id          the ID of the comment (not editable)
        user_id     the user ID which made a comment
        title       the comment title
        text        the comment body
        parent_id   <optional> a reference to the `comment` class - tells if comment is a response to another one;

    class like
        id          the ID of the like (not editable)
        user_id     user ID which makes the like
        post_id     the ID of the liked post

    class user_profile (extension)
        avatar      the avatar of the user

## Groups

### Admin

This is a blog owner. He creates the content and manage it.

### User

This is a blog consumer. He reads the content provided by Admin.

## Endpoints

    The request/response example in the yml definition.

    * GET /blog/posts/ - list post
    * GET /blog/posts/<id>/ - single post
    * POST /blog/posts/ - add post
    * PUT/PATCH /blog/post/ - edit post
    * DELETE /blog/posts/<id>/ - remove post
    * POST /blog/posts/<id>/publish/ - publish post
    * POST /blog/posts/<id>/schedule/ - schedule post
    * POST /blog/posts/<id>/unpublish/ - unpublish post
    * POST /blog/posts/<id>/like/ - add like to post
    * GET /blog/posts/<id>/like/ - get post likes
    * POST /blog/posts/<id>/comments/ - add a comment
    * GET /blog/posts/<id>/comments/ - list comments
    * POST /blog/login/ - login user/admin
    * POST /blog/register/ - register user
    * POST /blog/media/ - add media
    * PUT/PATCH /blog/media/<id>/ - update media
    * DELETE /blog/media/<id>/ - removes media

## Hosting Socket

In this Socket the very desired functionality is to define the Hosting Socket as a dependency to the original Socket.
This will allow to easily modify the hosted files and also gives Syncano user a whole `product` - not only the API.

The Hosting Socket in yml can look like this:

    hosting: sites

Which means that the Socket installation process will also automatically move all the files from sites to the Hosting Socket
(publish the page under the `sites` directory).

## YML definition

    name: blog
    description: Blog application

    endpoints:
      posts:
        object: post
        parameters:
          title: string
          text: text
          image: integer

        acl:
          groups:
            _admin: *
            _user:
              - GET
      media:
        object: media
        parameters:
          title: string
          media: file
          size: string
          type: integer

        acl:
          groups:
            _admin: *
            _user:
              - GET

      comments:
        object: comment
        parent: post
        parameters:
          title: string
          media: file
          size: string
          type: integer

        acl:
          groups:
            _admin: *
            _user: *

      like:
        object: like
        parent: post
        parameters:
          user_id: integer
          post_id: integer

        acl:
          groups:
            _admin: *
            _user: *

      login:
        POST:
          script: login
        parameters:
          username: string
          password: string
          avatar: file <optional>

      register:
        POST:
          script: register
        parameters:
          username: string
          password: string

      schedule:
        action: true
        parent: post
        script: schedule

      publish:
        action: true
        parent: post
        script: publish

      unpublish:
        action: true
        parent: post
        script: unpublish

    dependencies:
      objects:
        post:
          description: Post object;
        media:
          description: Image object;
        comment:
          description: Comment object;
        like:
          description: Like object;

      hostings:
        hosting: site
        description: a Hosting files for blog platform

      scripts:
        login:
          description: Exchange user/password for token;
        register:
          description: Register new user;
        publish:
          description: Publish post;
        unpublish:
          description: Unpublish the post;
        schedule:
          description: Schedule the post;

    classes:
      post:
        schema:
          - name: id
            type: integer
          - name: created_at
            type: datetime
          - name: updated_at
            type: datetime
          - name: created_by
            type: integer
          - name: updated_by
            type: integer
          - name: title
            type: string
          - name: text
            type: text
          - name: image
            type: integer
          - name: status
            type: integer

      media:
        schema:
          - name: id
            type: integer
          - name: title
            type: string
          - name: media
            type: file
          - name: size
            type: string
          - name: type
            type: integer

      comment:
        schema:
          - name: id
            type: integer
          - name: user_id
            type: integer
          - name: title
            type: string
          - name: text
            type: string
          - name: parent_id
            type: string

      like:
        schema:
          - name: user_id
            type: integer
          - name: post_id
            type: integer

      user_profile:
        schema:
          - name: avatar
            type: file

    groups:
      - name: admin
      - name: user


## Summary and comments

Basically I've drove off a little :)

I know that this socket can be done in current way of how Syncano Custom Sockets works. But writing a scripts for simple CRUD
operations seems like a misunderstanding. Also - the usa of the `administrator` API for that - is not so nice to the end user.
So I've came up with an idea of new dependecy: objects, which maybe sometime will be existing :) This dependecy provides a simple
CRUD API for given object, for example:

    class Message
      id: integer
      body: text
      send_date: datetime

and dependency:

    dependecies:
      objects:
        message:
          description: Message CRUD

Will give to the user following endpoints:

  * GET /messages/
  * POST /messages/
  * GET /messages/<id>/
  * PUT /messages/<id>/
  * PATCH /messages/<id>/
  * DELETE /messages/<id>/

Which is basically a CRUD operations for model Message;

Additionally I came up with an idea of some `action` script for CRUD operations. In the above example such action is publish:

  * /blog/posts/<id>/publish/

Which simply - change the status of the blog post. Such actions is similar to the drf decorator: @detail_route
And the logic can be processed in custom script;

What more?
Well - for such Sockets it would be nice to have Hosting Socket dependency.
The Socket installation process should also publish hosting files.
Additionally it can ask for such things as custom domain and so on.

This example is only the tip of the iceberg - I've intentionally omitted such subjects as: statistics and user analytics.
But both of them are very desirable in blog.