apiary.apib

FORMAT: 1A
HOST: http://api.dobigcrossword.com/

# DoBigCrossword

This API is able to handle the functionality of a multiuser crossword creator site

## Authentication Account [/auth/account/]

### Register a user [POST]

Use this function if you want to create a new user. Returns
- 200 if the registration was successful 
- 403 if the email address is already in use
- 403 if the password is wrong (too short, too long, too simple, etc.)

+ Request (application/json)

        {
            "email": "johndoe@gmail.com",
            "password": "abc123",
            "displayed_name": "Pocak"
        }


+ Response 200 (application/json)

        {
            "result": "OK"
        }


+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "Email address already in use."
        }

+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "The password doesn't meet the requirements."
        }

### Check if email address exists [GET]

With this function the client can check whether a given email address is already in use or not. It returns
- 200 if the email address is a valid email address, in this case the `is_existing` field contains the boolean value whether the email address is already used or not
- 400 if the email address is invalid


+ Request (application/json)

        {
            "email": "johndoe@gmail.com",
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "is_existing": false
        }

+ Response 400 (application/json)

        {
            "result": "ERROR",
            "message": "The email address in invalid."
        }
        
## Login [/auth/login/]

### Log in a user [POST]

Use this function to log in a user.
- 200 if the registration was successful. In this case a token is returned which has to be used for the further communication and identification of the user. 
- 403 if the email address and/or the password are wrong

+ Request (application/json)

        {
            "email": "johndoe@gmail.com",
            "password": "abc123",
        }


+ Response 200 (application/json)

        {
            "result": "OK",
            "token": "a546b362c73d84f95f003c66ab3ed0c9"
        }


+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "Email address or password is wrong."
        }

### Logout [DELETE]

Use this function to invalidate the user's token (DELETE the is-logged-in status).
- 200 if the invalidation was successful (the user was logged in and is not logged in anymore).
- 403 if the user was not logged in

+ Request (application/json)

        {
            "token": "a546b362c73d84f95f003c66ab3ed0c9"
        }


+ Response 200 (application/json)

        {
            "result": "OK",
        }


+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "There was no logged in user with this token."
        }
        
## Password Reset [/auth/password_reminder/]

### Password reminder [POST]

Use this function to request a password reminder email.
- 200 if the email address exists. It returns the normalised form of the email address where the password reminder email has been sent to. The email contains a link to the password reset page and a verification code. If the user visits the password reset page then they should provide the email address, the verification code and the new password. Then the new password is set for the user.
- 403 if the email address doesn't exist

+ Request (application/json)

        {
            "email": " John.Doe@gmail.com  "
        }


+ Response 200 (application/json)

        {
            "result": "OK",
            "email": "johndoe@gmail.com"
        }


+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "Unknown email address."
        }

### Password reminder [PUT]

Use this function to adjust a new password.
- 200 if the email address exists and based on the verification code, the new password for that user has been set succesfully. 
- 403 if the email address doesn't exist.
- 401 is the email address exists but the verification code is incorrect.

+ Request (application/json)

        {
            "email": "John.Doe@gmail.com",
            "verification_code": "2wd8y4j9fw6dc8",
            "new_password": "abCD@1234"
        }


+ Response 200 (application/json)

        {
            "result": "OK",
            "email": "johndoe@gmail.com"
        }


+ Response 403 (application/json)

        {
            "result": "ERROR",
            "message": "Unknown email address."
        }

+ Response 401 (application/json)

        {
            "result": "ERROR",
            "message": "Wrong verification code"
        }
        
## Crosswords [/crosswords/]

### List of crosswords [GET]

Returns the list of the crosswords the user is allowed to list. The user is determined from the token. 

The `title_filter` can contain asterisk symbols as wildcards standing for zero or more characters. If not given then there is no filtering based on title. The matching is not case sensitive.

The `order_by` specifies in what order the results are to return. Default is `-creation_time`. 
Possible orders:
- `creation_time`:  when the crossword was created
- `last_edited`: when the crossword was changed last time
- `title`: title of the crossword
- `num_cells`: number of the cells within the crossword (=width*height)
- `manager`: the crossword manager's name

The `order_by` value means ascending order, or can be prefixed by minus symbol to indicate descending order.

Example: `"order_by": ["-manager", "title"]`

The elements of the `order_by` value mean primary, secondary, etc. ordering rules. 

+ Request (application/json)

        {
            "title_filter": "*ssword of S*",
            "order_by": ["creation_time"],
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "crosswords": [
                {
                    "crossword_id": 1,
                    "title": "Crossword for Sati",
                    "last_edited": "2016-12-31 23:59:59",
                    "manager_id": 1,
                    "manager_name": "Pocak"
                },
                {
                    "crossword_id": 2,
                    "title": "Another crossword",
                    "last_edited": "2017-12-31 23:59:59",
                    "manager_id": 1,
                    "manager_name": "Pocak"
                }
            ]
        }



## Crossword [/crossword/]

### Create a new crossword [POST]

Creates a new crossword. The `join_policy` may have the following values with the corresponsing meaning:
- `opened`: everybody can join if want
- `approved`: the user may send a request to the crossword manager who can approve or disprove the join request
- `invitation`: the crossword manager can send invitations to other users in email who can join to this crossword if they want

+ Request (application/json)

        {
            "width": 64,
            "height": 48,
            "title": "Birthday Crossword for Sati #90",
            "join_policy": "everybody"
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "crossword_id": 1
        }

### Modify an existing crossword [PUT]

Changes some attributes of a crossword. 
The `resize_method_*` are ignored if the corresponding `width` and `height` parameters are not given. Their possible values are the followings:
- `centre`: the central column/row of the new crossword will be the central column/row of the old crossword. For the rounding rules, see below.
- `change-top`: the topmost rows will be removed or empty rows will be inserted there
- `change-left`: the leftmost columns will be removed or empty columns will be inserted there
- `change-bottom`: the bottommost rows will be removed or empty rows will be inserted there
- `change-right`: the rightmost columns will be removed or empty columns will be inserted there
In case of `centre` resize_methods, the following rounding rules are to be applied:
- If the number of new columns/rows to insert is an odd number then below/right from the old content will be one more column inserted. That is, the old content will be shifted by half cell towards the upper left corner.
- If the number of new columns/rows to delete is an odd number then above/left from the old content will be one more column deleted. That is, the old content will be shifted by half cell towards the upper left corner.

Examples: 
- If the crossword has 1*1 cell and the following structure arrives:

      {
          "width": 10,
          "height": 8,
          "resize_method_horizontal": "change-left",
          "resize_method_vertical": "centre"
      }    

then the new crossword will have 10 columns and 8 rows (adding 9 columns and 7 rows) and the original cell will have 9 new cells on its left, 3 cells above it and 4 below. 

- If the crossword has 4*4 cell and the following structure arrives:

      {
          "width": 3,
          "height": 1,
          "resize_method_horizontal": "change-left",
          "resize_method_vertical": "centre"
      }

then the new crossword will have 3 columns and 1 row (deleting one column and 3 rows). In this case the three cells of the new crossword will be last three cells of the second row of the original crossword.

    Like this:   
      
    ABCD
    EFGH    =>  FGH
    IJKL   
    MNOP

If the `manager_id` field is present then the new manager will get a notification email that they are invited to be the new manager of the crossword. They have to accept this invitation via the invitation API. Until it is accepted, the manager is still theold manager.

+ Request (application/json)

        {
            "width": 64,
            "height": 48,
            "resize_method_horizontal": "centre",
            "resize_method_vertical": "change-top",
            "title": "Birthday Crossword for Sati #90",
            "join_policy": "everybody",
            "manager_id": 2
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "crossword_id": 1
        }

### Return details of a crossword [GET /{crossword_id}]

Return details of the requested crossword.
- `width` and `height` are the dimensions of the crossword
- `num_black` is the number of cells that are set to black
- `num_letters` is the number of the cells that have assigned a letter
The following fields are not returned because they can be derived from other values:
- `num_white` = `width` * `height` - `num_black`
- `filled_ratio` = ( `num_black` + `num_letters` ) / ( `width` * `height` )
The timestamps are returned in UTC.


+ Request (application/json)

        {
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "crossword_id": 1,
            "width": 20,
            "height": 10,
            "num_black": 30,
            "num_letters": 40,
            "creation_at": "2000-12-31 23:59:59",
            "lasd_modified_at": "2001-12-31 23:59:59",
            "manager": {
                "user_id": 1,
                "user_name": "pocak"
            }
        }

+ Response 404 (application/json)

        {
            "result": "Error",
            "message": "The crossword doesn't exist."
        }

+ Response 401 (application/json)

        {
            "result": "Error",
            "message": "There is no permission the create allocations for the user"
        }

### Return users of a crossword and their statistics [GET /{crossword_id}/users]

Returns the users of the given crossword. For each user it tells how many letters and how many black cells are defined by them. 

+ Request (application/json)

        {
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "users": [
                {
                    "user_id": 1,
                    "user_name": "pocak",
                    "registered_at": "2000-12-31 23:59:59",
                    "num_letters": 12,
                    "num_black": 23
                },
                {
                    "user_id": 2,
                    "user_name": "ciri",
                    "registered_at": "2000-12-31 23:59:59",
                    "num_letters": 12,
                    "num_black": 23
                }
            ]
        }

+ Response 404 (application/json)

        {
            "result": "Error",
            "message": "The crossword doesn't exist."
        }

+ Response 401 (application/json)

        {
            "result": "Error",
            "message": "There is no permission the create allocations for the user"
        }

       
## Allocations [/allocation/]

### Create an allocation [POST]

Creates a new allocation for a user (and unallocate the previous one if it exists) in the given crossword.

If the user is not given then the user defined by the token is used. If the user is given and is different from the token's user then the requester has to be the manager of the crossword.

The `allocations` member of the response is an N-digit-long string where N = `width` * `height` from the request and which contains `1`s for each successfully allocated cells and `0`s for the unsuccessfull ones, row by row. A cell allocation may be unsuccessful if the cell is alreaady allocated by someone else. 

- 200 if the allocation is partly or completely successful (0 or more cells were successfull allocated)
- 404 if the requester has no right to allocate cells for the user.

+ Request (application/json)

        {
            "crossword_id": 1,
            "user_id": 1,
            "x": 0,
            "y": 10,
            "width": 20,
            "height": 15
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "x": 0,
            "y": 10,
            "width": 2,
            "height": 3,
            "allocations": "111100"
        }

+ Response 404 (application/json)

        {
            "result": "Error",
            "message": "The crossword doesn't exist."
        }

+ Response 401 (application/json)

        {
            "result": "Error",
            "message": "There is no permission the create allocations for the user"
        }

### Delete the allocation of a user [DELETE]

Deletes the current allocation of the user. If the user is not given then the user belonging to the token is used. 

+ Request (application/json)

        {
            "crossword_id": 1,
            "user_id": 1
        }

+ Response 200 (application/json)

        {
            "result": "OK"
        }

+ Response 404 (application/json)

        {
            "result": "Error",
            "message": "There is no permission to delete allocations for the user"
        }

## Cells [/cells/]

### Returns the current values of the cells within an area [GET]

Returns the cells of the given crossword within the requested area. 
- The "letters" in the response contain the letters of the subsequent cells row-by-row. Empty cells are represented by spaces, black cells by chr(127).
- The "allocators" is the user_ids of the users who allocated each cells (in same order as "letters").
- The "definitions" is the list of the cells in random order that have horizontal and/or vertical definition.

+ Request (application/json)

        {
            "crossword_id": 1,
            "x": 0,
            "y": 10,
            "width": 20,
            "height": 15
        }

+ Response 200 (application/json)

        {
            "result": "OK",
            "x": 0,
            "y": 10,
            "width": 3,
            "height": 2,
            "letters": "AB CDE",
            "allocators": [
                1000,
                1000,
                1000,
                1001
                null,
                999
            ],
            "definitions": [
                {
                    "x": 0,
                    "y": 0,
                    "v_def": "Vertical definition",
                    "h_def": "Horizontal definition"
                },
                {
                    "x": 0,
                    "y": 1,
                    "v_def": "Capital of Australia"
                },
            ]
        }

+ Response 401 (application/json)

        {
            "result": "Error",
            "message": "The user is not allowed to read the crossword data."
        }

+ Response 404 (application/json)

        {
            "result": "Error",
            "message": "The crossword doesn't exist."
        }