Hello!

documenting

# Pinote-service
pinote-service is a web *API* design to pinote app written in [Lua](http://www.lua.org) that runs over [Gin](http://gin.io) and [Openresty](http://openresty.org)

# Table of contents
* [Status](#markdown-header-status)
* [Instalation](#markdown-header-instalation)
* [Deploy](#markdown-header-deploy)
* [API](#markdown-header-api)
    * [Overall specifications](#markdown-header-overall-specifications)
        * [*](#markdown-header-42)
        * [the accept header](#markdown-header-the-accept-header)
        * [covered http status and its return](#markdown-header-covered-http-status-and-its-return)
    * [Users](#markdown-header-users)
        * [parameters](#markdown-header-parameters_1)
        * [create user](#markdown-header-create-user)
        * [return an user by id](#markdown-header-return-an-user-by-id)
        * [update an user by id](#markdown-header-update-an-user-by-id)
        * [delete an user by id](#markdown-header-delete-an-user-by-id)
    * [Session](#markdown-header-session)
        * [parameters](#markdown-header-parameters_2)
        * [tokens](#markdown-header-tokens)
        * [create user session (login)](#markdown-header-create-user-session-login)
        * [read (get) user session](#markdown-header-Read-get-user-session)
        * [delete user session (logout)](#markdown-header-delete-user-session-logout)
    * [Groups](#markdown-header-groups)
      * [parameters](#markdown-header-parameters_3)
      * [create group](#markdown-header-create-group)
      * [read group and listing](#markdown-header-read-group-and-listing)
      * [update group](#markdown-header-update-group)
      * [delete group](#markdown-header-delete-group)
    * [Permissions](#markdown-header-permissions)
      * [parameters](#markdown-header-parameters_4)
      * [create permission](#markdown-header-create-permission)
      * [read permission and listing](#markdown-header-read-permission-and-listing)
      * [update permission](#markdown-header-update-permission)
      * [delete permission](#markdown-header-delete-permission)
    * [Strategies](#markdown-header-strategies)
      * [parameters](#markdown-header-parameters_5)
      * [create strategy](#markdown-header-create-strategy)
      * [read strategy and listing](#markdown-header-read-strategy-and-listing)
      * [update strategy](#markdown-header-update-strategy)
      * [delete strategy](#markdown-header-delete-strategy)

# Status

# Instalation

# Deploy

# API
  
* This *json API* runs over an *REST framework* and should respect all *http verbs* [...] and *stateless* either;

* All transactions should be done using *SSL* (not implemented yet);

* All data transaction between client and server is done thru *query string* or *json encoded body* always returning a *json* or *empty* response due to *http status code*;

* Some browsers does not support all *http verbs*, due to it - this *API* supports the header *X-HTTP-Method-Override*.

## Overall specifications

### \*
means mandatory token should be sent to *endpoint*, example of a http request:
```
GET /user/420 HTTP/1.1
Host: pinote.simbio.se
User-Agent: pinote-app/1.0
Accept: application/vnd.pinote.v1+json
Token: DJUKHy6jipO0GxQFJx0RemHT7swCrC50
```
### The accept header
All requests should send *accept* header, *accept* header consists of *application name*, *API version* and *mime type* (*JSON* only), example:
```
Accept: application/vnd.pinote.v1+json
```
### covered http status and its return

**200** *or* **OK**, used in a successful *GET* response together with a *JSON* body.

**201** *or* **Created**, used in a successful *POST* response together with a *JSON* body.

**204** *or* **No Content**, used in a successful *PUT* or *DELETE* response with an empty body.

**400** *or* **Bad Request**, is present in most responses due to error or missing fields, there is also a *JSON* body with description of error.

**401** *or* **Unauthorized**, is present in most responses due to unauthorized *Token* or missing *Token*.

**404** *or* **Not Found**, unreachable resource.

## Users
This *endpoint* manage the CRUD of User(s).

### parameters

| ****          | ****                                                                                                                                  |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------|
| **birthdate** | date ***mm/dd/yyyy***, not required                                                                                                   |
| **password**  | not required                                                                                                                          |
| **gender**    | not required, defaults to ***unknown***, possible values are ***male***, ***female***, ***other*** and ***unknow***                   |
| **i18n**      | required, possible values are ***pt***, ***pt-br***, ***en***, ***en-us***, ***en-ca***, ***en-gb***, ***fr***, ***de*** and ***es*** |
| **status**    | not required, defaults to ***enabled***, possible values are ***enabled***, ***disabled*** and ***invited***                          |
| **username**  | *string* with 20 characters long, not required                                                                                        |
| **name**      | *string* with 60 characters long, not required                                                                                        |
| **email**     | *string* containing a valid e-mail with 60 characters long, required                                                                  |
| **pic**       | *string* containing a encoded *base64* image, not required                                                                            |
| **strategy**  | optional, should be used together with ***socialId***, possible values are ***facebook*** and ***google***                            |
| **socialId**  | optional, *string* with *social id*, should be used together with ***strategy***                                                      |
| **model**     | required, *string* identifing device model                                                                                            |
| **os**        | required, possible values are ***android***, ***osx***, ***ios***, ***windows***, ***linux***, ***unix*** and ***other***             |
| **type**      | required, possible values are ***tv***, ***phone***, ***tablet***, ***pc***, ***mac*** and ***other***                                |

### Create user
POST *user*

with a *JSON* payload, example:
```json
{
    "email":"[email protected]", "password":1234, "username":"Xico Leite",
    "socialId":12323232, "strategy":"facebook", "model":"dell pc",
    "os":"linux", "type":"pc", "i18n":"en"
}
```
returns **Bad Request** or **Created** with:
```json
{
    "expires":691200, "id":420, "deviceId":569,
    "refreshToken":"PL4ch1Nl1LFpnurZrCheCumOfS6QP1lr",
    "accessToken":"zClfHjzhDOfT00WIJBtaO2BPTkq3cY6v"
}
```
### Return an user by id
GET *user/:id* **\***

returns **Bad Request**, **Unauthorized**, **Not Found** or **OK** in a successful request, example:
```json
{
    "i18n":"en", "email":"[email protected]",
    "id":1, "status":"enabled", "gender":"unknown"
}
```
### Update an user by id
PUT *user/:id* **\***
```json
{
    "email":"[email protected]", "password":"1234", "username":"Xico Leite",
    "i18n":"en"
}
```
returns **Bad Request**, **Unauthorized**, **Not Found** or **No Content** in a successful request.

### Delete an user by id
DELETE *user/:id* **\***

returns **Bad Request**, **Unauthorized**, **Not Found** or **No Content** in a successful request

## Session
stateless session

### parameters

| ****             | ****                                                                                                                                                                                    |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **refreshToken** | required to "renew" session                                                                                                                                                             |
| **password**     | required when user lost it's session                                                                                                                                                    |
| **username**     | *string* with 20 characters long, required when user lost its session, can be replaced with **email**                                                                                   |
| **email**        | *string* containing a valid e-mail with 60 characters long, required when user lost its session, can be replaced with **username**                                                      |
| **model**        | required together with **email**/**username** and **password** "login", *string* identifing device model                                                                                |
| **os**           | required together with **email**/**username** and **password** "login", possible values are ***android***, ***osx***, ***ios***, ***windows***, ***linux***, ***unix*** and ***other*** |
| **type**         | required together with **email**/**username** and **password** "login", possible values are ***tv***, ***phone***, ***tablet***, ***pc***, ***mac*** and ***other***                    |

### Tokens
something something token [...]

### Create user session (login)
POST *session* 
```json
{
    "username":"Xico Leite", "password":"1234",
    "model":"dell pc", "os":"linux", "type":"pc"
}
```
***or***
```json
{"refreshToken":"PL4ch1Nl1LFpnurZrCheCumOfS6QP1lr"}
```
***yet***
```json
{
    "strategy":"facebook",
    "socialCode":"zClfHjzhDOzClfHjzhDOzClfHjzhDOfT0zClfHjzhDOfT00WIJBtaO2BPTkq3cY6v=="
}
```
returns **Bad Request**, **Unauthorized** or **Created** with:
```json
{
    "expires":691200, "deviceId":569,
    "refreshToken":"yYC8kbFdRTSCG6sALLbgCumOfS6QP1lr",
    "accessToken":"vSJfreVb9anAG7PErS4EBPTkq3cY6v87"
}
```

### Read (get) user session
GET *session* **\***

returns **Bad Request**, **Unauthorized** or **OK** in a successful request, example:

```json
{
    "expires":691000, "deviceId":569,
    "refreshToken":"yYC8kbFdRTSCG6sALLbgCumOfS6QP1lr",
    "accessToken":"vSJfreVb9anAG7PErS4EBPTkq3cY6v87"
}
```

### Delete user session (logout)
DELETE *session* **\***

returns **Bad Request**, **Unauthorized** or **No Content** in a successful request.

## Groups
create user's groups

### parameters
| ****             | ****                                                                                                                                                                                    |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **name** | required, *string* with 45 characters long                                                                                                                                                              |
| **status**     | required, possible values are **enabled** or **disabled**                                                                                                                                                    |
| **permissions**     | array of *integers* related to permissions                                                                                  

### Create group
POST *group*
```json
{
    "username":"Xico Leite", "password":"1234",
    "model":"dell pc", "os":"linux", "type":"pc"
}