apiary.apib

FORMAT: 1A
HOST: https://api.voisee.jp

# Voisee API

## Authentication

The API server implements the OAuth2 protocol with the following routes

```
GET       /oauth/authorize/:code
GET       /oauth/authorize
POST      /oauth/authorize
PUT       /oauth/authorize
DELETE    /oauth/authorize
POST      /oauth/token
POST      /oauth/revoke
resources /oauth/applications
GET       /oauth/authorized_applications
DELETE    /oauth/authorized_applications/:id
GET       /oauth/token/info
```

See [doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) gem documentation
for more information.

## Roles

There are three different roles:

* Store group
    * Can own one/multiple applications
    * Can manage own application
    * Can manage all stores in a store group

* Store
    * Owns and manage application
    * Can belong to multiple store groups
    * Can manage store page in store group application
    * Can upgrade/downgrade store plan

## Media Types

When applicable, this API returns JSON encoded
objects or arrays.
A list action will always return a JSON array,
while a get action will always return a JSON object.

## Pagination

All endpoints returning list accept the following parameters:

* min_id (optional, integer) ... The minimum ID to return. Default: `null`
* max_id (optional, integer) ... The maximum ID to return. Default: `null`
* count (optional, integer) ... The number of items to return. Default: `20`

All paginated responses contain the `X-Total-Count` header.

## Error States

The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

## Payment

All payments will use [WebPay](https://webpay.jp/).

## Plugins

All requests under the `/p` namespace will be forwarded to the plugin API if they have sufficient permission.

# Group Store Group

A group of store representing either a mall, or a commercial district.


## Store group [/store_groups/{id}]

Requires Store group role.


### Get store group [GET]

Get information about the store group.

+ Response 200
    + Body

        ```json
        {
            "id": 1,
            "name": "某商店街"
        }
        ```

## Stores [/store_groups/{id}/stores]

### List stores [GET]

List all approved stores in the store group.
Requires Store group role.

+ Response 200
    + Body

        ```json
        [
            {
                "id": 1,
                "name": "Toranoko",
                "approved": true,
                "created_at": "2015-04-27T18:37:52+09:00",
                "updated_at": "2015-04-27T18:42:52+09:00"
            }
        ]
        ```

### Create store [POST]

Creates a store in the Store Group.
The store is not made public until the `stores/{id}/approve` API is called.

+ Request

    + Body

        ```json
        {
            "name": "Toranoko"
        }
        ```

+ Response 201

    [Store]

    + Body

        ```json
        {
            "id": 1,
            "name": "Toranoko",
            "approved": false,
            "created_at": "2015-04-27T18:37:52+09:00",
            "updated_at": "2015-04-27T18:42:52+09:00"
        }
        ```

# Group Store

## Approve store [/stores/{id}/approve]

Requires Store group role.

### Approve store [POST]

+ Response 204

## Store [/stores/{id}]

### Get a store [GET]

Requires Store group role or store role with `id` matching current store.

+ Response 200

    + Body

        ```json
        {
            "id": 1,
            "name": "Toranoko",
            "approved": true,
            "available_credit_card": false,
            "plan": {
                "id": 1,
                "type": "standard"
            },
            "created_at": "2015-04-27T18:37:52+09:00",
            "updated_at": "2015-04-27T18:42:52+09:00"
        }
        ```

### Update a store [PUT]

Requires store role.

+ Request

    + Body

        ```json
        {
            "name": "toranoko"
        }
        ```

+ Response 200

    + Body

        ```json
        {
            "id": 1,
            "name": "toranoko",
            "plan": {
                "id": 1,
                "type": "standard"
            },
            "created_at": "2015-04-27T18:37:52+09:00",
            "updated_at": "2015-04-27T18:42:52+09:00"
        }
        ```

## Store plan [/stores/{id}/plan]

### Update plan [PUT]

Updates the current pricing plan. Requires store role.
To upgrade to premium plan, credit card information is needed.

+ Request

    + Body

        ```json
        {
            "type": "premium"
        }
        ```

+ Response 204

# Group Store application

## Application [/stores/{id}/application]

+ Model

    + Body

        ```json
        {
            "status": "published",
            "version": "0.4.1",
            "configuration": "{\"theme\": \"brown\", \"plugins\": [\"news\", \"coupons\"]}"
        }
        ```

### Get application [GET]

Requires store permission. Get the store application

+ Response 200

    [Application][]


### Update application [PUT]

Requires store permission. Creates or updates the store application.

+ Request

    + Body

        ```json
        {
            "configuration": "{\"theme\": \"brown\"}"
        }
        ```

+ Response 200

    [Application][]

# Group Plugins


Available plugins are:

## News

Sample news:

    {
        "id": "5541e298f27ae7da50d17816",
        "title": "2月24日に、本マグロの解体ショーを行います！",
        "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
        "publishAt": "2015-02-18T16:54:25.473Z",
        "images": [{
            "id": "5541e298f27ae7da50d17816",
            "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
            "originalWidth": 800,
            "originalHeight": 600,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }],
        "applicationId": 14,
        "commentsCount": 3,
        "likesCount": 4,
        "viewsCount": 18,
        "createdAt": "2015-02-18T16:54:25.473Z",
        "updatedAt": "2015-02-18T16:54:25.473Z",
        "deletedAt": null
    }

## Voices

Sample voice:

    {
        "id": "5541e298f27ae7da50d17816",
        "body": "2月24日に、本マグロの解体ショーを行います！",
        "images": [{
            "id": "5541e298f27ae7da50d17816",
            "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
            "originalWidth": 800,
            "originalHeight": 600,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }],
        "author": {
            "id": 8,
            "displayName": "だにー",
            "profileImage": {
                "id": "5541e298f27ae7da50d17716",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }
            },
        "applicationId": 14,
        "commentsCount": 3,
        "likesCount": 4,
        "viewsCount": 18,
        "createdAt": "2015-02-18T16:54:25.473Z",
        "updatedAt": "2015-02-18T16:54:25.473Z",
        "deletedAt": null
    }

## Coupons

Sample coupon:

    {
        "id": "5541e298f27ae7da50d17816",
        "title": "★フードもドリンクも♪全メニュー10％OFF!★",
        "conditions": "ご来店のさいにご提示ください。また、他のクーポンやサービスとの併用できません。",
        "expiresAt": "2015-02-18T16:54:25.473Z",
        "image": {
            "id": "5541e298f27ae7da50d17816",
            "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
            "originalWidth": 800,
            "originalHeight": 600,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        },
        "applicationId": 14,
        "commentsCount": 3,
        "likesCount": 4,
        "viewsCount": 18,
        "createdAt": "2015-02-18T16:54:25.473Z",
        "updatedAt": "2015-02-18T16:54:25.473Z",
        "deletedAt": null
    }

# Comments

Sample comment:

    {
        "id": "5541e298f27ae7da50d17816",
        "body": "とてもいい意見だと思います。",
        "applicationId": 14,
        "author": {
            "id": 8,
            "displayName": "だにー",
            "profileImage": {
                "id": "5541e298f27ae7da50d17716",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }
        },
        "item": {
            "itemId": "4541e298f27ae7da50d17716",
            "type": "news"
        },
        "likesCount": 4,
        "createdAt": "2015-02-18T16:54:25.473Z",
        "updatedAt": "2015-02-18T16:54:25.473Z",
        "deletedAt": null
    }

## Plugin items collection [/p/{plugin}]

+ Parameters
    + plugin: news (enum[string], required) - The plugin to use
        + Members
            + news
            + voices
            + coupons
            + comments

### List items [GET]

List plugin items.

+ Response 200 (application/json)

    + Body

        ```json
        [{
            "id": "5541e298f27ae7da50d17816",
            "title": "2月24日に、本マグロの解体ショーを行います！",
            "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
            "images": [{
                "id": "5541e298f27ae7da50d17816",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }],
            "applicationId": 14,
            "commentsCount": 3,
            "likesCount": 4,
            "viewsCount": 18,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "publishedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }]
        ```

### Post item [POST]

+ Request

    + Body

        ```json
            {
                "title": "2月24日に、本マグロの解体ショーを行います！",
                "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
                "publishedAt": "2015-02-18T16:54:25.473Z",
                "images": [
                    "5541e298f27ae7da50d17816",
                    "5541e298f27ae7da50d18817"
                ],
                "applicationId": 14
            }
        ```

+ Response 201 (application/json)

    + Body

        ```json
        {
            "id": "5541e298f27ae7da50d17816",
            "title": "2月24日に、本マグロの解体ショーを行います！",
            "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
            "images": [{
                "id": "5541e298f27ae7da50d17816",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }],
            "applicationId": 14,
            "commentsCount": 0,
            "likesCount": 0,
            "viewsCount": 0,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "publishedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }
        ```

## Plugin item resource [/v1/{plugin}/{id}]

+ Parameters
    + id: 5541e298f27ae7da50d17816 (string, required) - The id of the item
    + plugin: news (enum[string], required) - The plugin to use
        + Members
            + news
            + voices
            + coupons
            + comments

### Retrieve item [GET]

+ Response 200 (application/json)

    + Body

        ```json
        {
            "id": "5541e298f27ae7da50d17816",
            "title": "2月24日に、本マグロの解体ショーを行います！",
            "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
            "images": [{
                "id": "5541e298f27ae7da50d17816",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }],
            "applicationId": 14,
            "commentsCount": 3,
            "likesCount": 4,
            "viewsCount": 18,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "publishedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }
        ```

### Update item [PUT]

+ Request

    + Body

        ```json
            {
                "title": "2月24日に、本マグロの解体ショーを行います！",
                "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
                "images": [
                    "5541e298f27ae7da50d17816",
                    "5541e298f27ae7da50d18817"
                ],
                "applicationId": 14
            }
        ```

+ Response 200 (application/json)

    + Body

        ```json
        {
            "id": "5541e298f27ae7da50d17816",
            "title": "2月24日に、本マグロの解体ショーを行います！",
            "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
            "images": [{
                "id": "5541e298f27ae7da50d17816",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }],
            "applicationId": 14,
            "commentsCount": 0,
            "likesCount": 0,
            "viewsCount": 0,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "publishedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": null
        }
        ```

### Update item [DELETE]

+ Response 200 (application/json)

    + Body

        ```json
        {
            "id": "5541e298f27ae7da50d17816",
            "title": "2月24日に、本マグロの解体ショーを行います！",
            "body": "本マグロの解体ショーの魅力は、何といってもそのスケールの大きさ。 解体する本マグロの重量は、ほとんどが200kgを超えるもの。\n時には、300kgを超える巨大本マグロを解体することもあります。 \n海の中で時速約90kmのスピードで止まることなく泳ぎ続ける本マグロは、15～18年でこの大きさに成長。本マグロは、このクラスが最も美味しいとされています。\n是非お越しください！",
            "images": [{
                "id": "5541e298f27ae7da50d17816",
                "url": "https://images.voisee.jp/uploads/image/file/15/v1424451244/sic8lrgd62agvpogjc4g.png",
                "originalWidth": 800,
                "originalHeight": 600,
                "createdAt": "2015-02-18T16:54:25.473Z",
                "updatedAt": "2015-02-18T16:54:25.473Z",
                "deletedAt": null
            }],
            "applicationId": 14,
            "commentsCount": 0,
            "likesCount": 0,
            "viewsCount": 0,
            "createdAt": "2015-02-18T16:54:25.473Z",
            "updatedAt": "2015-02-18T16:54:25.473Z",
            "publishedAt": "2015-02-18T16:54:25.473Z",
            "deletedAt": "2015-02-18T16:54:25.473Z"
        }
        ```