apiary.apib

FORMAT: 1A

# DDD frontend API

API collection to view and submit projects, consult archive and send votes

NOTE: This document is a **work in progress**.

# API use and format specification 

## Authentication
*DDD frontend API* uses [OAuth Authorization](https://oauth.net). First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.
+ Every token MUST be refreshed before its expiration time,
+ Token MUST be provided in `Authorization` header,
+ Toke MUST be provided for each request that requires authentication

## Filtering, Ordering, Pagination & Searching

### Filtering

This API can filter returned collections based on provided query parameters. Virtually any model field can be used as a filter.

For example, when requesting a list of movies from the /movies endpoint, you may want to limit these to only those of drama genre. This could be accomplished with a request like `GET /movies?genre=drama`. Here, genre is a query parameter that implements a filter.

### Ordering

This API can sort returned collections. A generic query parameter `sort` is used to describe sorting rules. This parameter can take a list of comma separated field, each with a possible unary negative to imply descending sort order.

E.g. `GET /movies?sort=-rating` - Retrieves a list of movies in descending order of user rating.

By default all resources are ordered by their creation time, from newest to oldest.

### Pagination

This API uses the [Link header - RFC 5988](http://tools.ietf.org/html/rfc5988#page-6) to include pagination details.

An example of a Link header is described in [GitHub documentation](https://developer.github.com/guides/traversing-with-pagination/).

This API returns total count of paged resources in `Total-Count` HTTP header.

### Searching

This API uses a generic parameter `search` to expose a full text search mechanism.

## HTTP Methods

This API uses HTTP verbs (methods) as following:

+ `GET` - *Read* - used to **read** (or retrieve) a representation of a resource,
+ `POST` - *Create* - used to **create** new resources. In particular, it's used to create subordinate resources.
+ `PUT` - *Update/Replace* - used for **update** capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body.
+ `PATCH` - *Update/Modify* - used for **modify** capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.
+ `DELETE` - *Delete* - used to **delete** a resource identified by a URI.

## Media Type

Where applicable this API MUST use the JSON media-type. Requests with a message-body are using plain JSON to set or update resource states.

`Content-type: application/json` and `Accept: application/json` headers SHOULD be set on all requests if not stated otherwise.

## Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://www.ietf.org/rfc/rfc2119).

## Representation of Date and Time

All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC.

When returning date and time-related data `YYYY-MM-DDThh:mm:ss.SSSZ` format MUST be used.

## Resource IDs

This API uses short non-sequential url-friendly unique ids. Every resource id MUST consists of 9 url-friendly characters: `A-Z`, `a-z`, `0-9`, `_` and `-`.

### Example
`a6vhAo3FG7t1`

## Status Codes and Errors

This API uses HTTP status codes to communicate with the API consumer.

+ `200 OK` - Response to a successful GET, PUT, PATCH or DELETE.
+ `201 Created` - Response to a POST that results in a creation.
+ `204 No Content` - Response to a successful request that won't be returning a body (like a DELETE request).
+ `400 Bad Request` - Malformed request; form validation errors.
+ `401 Unauthorized` - When no or invalid authentication details are provided.
+ `403 Forbidden` - When authentication succeeded but authenticated user doesn't have access to the resource.
+ `404 Not Found` - When a non-existent resource is requested.
+ `405 Method Not Allowed` - Method not allowed.
+ `406 Not Acceptable` - Could not satisfy the request Accept header.
+ `415 Unsupported Media Type` - Unsupported media type in request.

### Error response

This API returns both, machine-readable error codes and human-readable error messages in response body when an error is encountered.

#### Example

##### Validation Error

```js
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Invalid query parameters",
    "data": {
        "code": 10003,
        "validation": {
            "details":[
                {
                    "message": "\"name\" is required",
                    "path": "name",
                    "type": "any.required",
                    "context": {
                        "key": "name"
                    }
                },{
                    "message": "\"email\" must be a valid email",
                    "path": "email",
                    "type": "string.email",
                    "context": {
                        "value": "foo",
                        "key": "email"
                    }
                }
            ],
            "source": "query",
            "keys": [ "name","email" ]
        }
    }
}
```

##### Generic Error

```js
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Your account is suspended and is not permitted to access this feature",
    "data": {
        "code": 13003
    }
}
```

#### Error Codes Dictionary

+ `10003` - Invalid query parameters
+ `10005` - Date is not in ISO 8601 standard
+ `10010` - Invalid Content-Type
+ `10011` - Invalid User-Agent
+ `10012` - Invalid or missing Application-Id
+ `11001` - Invalid or expired token
+ `11003` - Bad authentication data - *Method requires authentication but it was not presented or was wholly invalid.*
+ `11005` - Account not allowed to access this endpoint
+ `13003` - Your account is suspended and is not permitted to access this feature

## Versioning

This API uses `Api-Version` header to identify requested version. Every **minor** version SHOULD be backward compatible. However, **major** versions MAY introduce *breaking changes*.

`Api-Version: 1.0.0`

This header SHOULD be present in every request. If not, API MUST use the newest available major release.

If requested version is not available, API SHOULD try to fall back to the next available minor release.

# Group API Authentication
## OAuth token exchange [/oauth/token]
Exchange credentials for `access_token`. Supported types:

+ `client_credentials`
+ [`urn:ietf:params:oauth:grant-type:jwt-bearer`](https://tools.ietf.org/html/draft-jones-oauth-jwt-bearer-03#section-6)

### Exchange credentials for token [POST]
+ Request
    + Attributes (OAuth grant request)
    + Headers

            Authorization: Basic ABCDEF

+ Response 200 (application/json)
    + Attributes (OAuth valid response)

+ Request
    + Attributes (OAuth bearer grant request)

+ Response 200 (application/json)
    + Attributes (OAuth valid response)

## OAuth 2 Bearer Token protected resource [/protected]
### Status [GET]
+ Request
    + Headers

            Authentication: Bearer JWT <token>

+ Response 200 (application/json)
    + Attributes (Server response)

# Group User Authentication

## User login [/auth/login]

Access tokens are required to access nearly all endpoints of this API.

### Retrieve a token [POST]

Allows to retrieve a valid JSON Web Token for username and password.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | No  |
| Has restricted scope    | No  |

+ Request (application/json)
    + Attributes
        + login: `john.doe@mail.com` (string, required) - User email address
        + password: `QXR0mi38a2` (string, required) - User password

+ Response 200 (application/json)
    + Attributes
        + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....` (string) - JSON Web Token.

## Refresh a token [POST /auth/refresh-token]

Allows to retrieve a new, valid JSON Web Token based on a valid JSON Web Token.

Expired tokens MUST NOT be refreshed.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes
        + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....` (string) - New JWT

## User registration [/auth/register]

### Register a new user [POST]

Creates a new user account.

+ Provided email address MUST be unique.
+ Passwords MUST have at least six characters.
+ Passwords MUST NOT contain the user name or parts of the user’s full name, such as his first name.
+ Passwords MUST use at least three of the four available character types: lowercase letters, uppercase letters, numbers, and symbols.

After successful registration a confirmation email MUST be sent to provided address.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | No  |

**Error codes**

|       |         |                                             |
|-------|---------| ------------------------------------------- |
| `400` | `4001` | Password doesn't match password guidelines  |
| `400` | `3001` | User already exists                         |

+ Request (application/json)
    + Attributes
        + email: `john.doe@mail.com` (string, required) - E-mail address.
        + password: `QXR0mi38a2` (string, required) - User password.

+ Response 201

# Group User

## Current user profile [/users/me]

Current user MUST be identifed by JWT provided in request header.

### Retrieve profile of the current user [GET]

Retrieves the profile of the current user.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (User)

### Partialy update a profile of the current user [PATCH]

Updates a profile of the current user setting the values of the parameters passed. Any parameters not provided will be left unchanged.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request (application/json)
    + Headers

            Authorization: JWT <token>
    + Attributes
        + name: `Ben` (string) - First name of the user.

+ Response 200 (application/json)
    + Attributes (User)

## User password [/users/me/password]

### Change a password of the current user [PUT]

Changes user password.

After password is changed all access tokens issued for this user prior to password change must be invalidated.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

**Error codes**

|       |         |                                           |
|-------|---------| ----------------------------------------- |
| `400` | `4001` | Password doesn't match password guidelines |

+ Request (application/json)
    + Headers

            Authorization: JWT <token>
    + Attributes
        + old_password: `secret` (string, required)
        + new_password: `$3C6e7` (string, required)

+ Response 200
    + Attributes
        + token: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` (string) - New JSON Web Token.

## User avatar [/users/me/avatar]

### Set user avatar [POST]

Sets user avatar.

Either upload the raw binary ( **media** parameter) of the file, or its base64-encoded contents ( **media_data** parameter). Use raw binary when possible, because base64 encoding results in larger file sizes.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

**Error codes**

|       |         |                       |
|-------|---------| --------------------- |
| `400` | `2001`  | File is too large     |
| `400` | `2002`  | Unsupported file type |

+ Request (multipart/form-data)
    + Headers

            Authorization: JWT <token>

+ Response 200
    + Attributes
        + avatar: `https://...` (string) - Public download URL

### Delete user avatar [DELETE]

Restores user avatar to the default one.

**Endpoint information**

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 204

## Users [/users]

### List all users [GET]

Returns a list of users. The users are returned in sorter order, with the most recently created user accounts appearing first.

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (array[User])

## User [/users/{id}]

+ Parameters
    + id: `a6vhAo3FG7t1` (string) - id of the user.

### Retrieve a user [GET]

Retrieves the details of an existing user.

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

**Error codes**

|       |         |                               |
|-------|---------| ----------------------------- |
| `400` | `1000`  | Referenced resource not found |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (User)

+ Response 404

# Group Projects

## Projects [/projects]

### List all projects [GET]

Returns a list of votable projects. The projects are returned based on incremental expire date.

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (array[Project])

## Project [/projects/{id}]

+ Parameters
    + id: `a6vhAo3FG7t1` (string) - id of the project.

### Retrieve a project [GET]

Retrieves the details of an existing project.

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

**Error codes**

|       |         |                               |
|-------|---------| ----------------------------- |
| `400` | `1000`  | Referenced resource not found |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (Project)

+ Response 404

# Group Categories

## Category [/category]

### Category list [GET]

Returns a category list

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (array[Category])

## Category detail [/category/{id}]

+ Parameters
    + id: `a6vhAo3FG7t1` (string) - category id.

### Retrieve a category [GET]

Retrieves the category details and all related projects.

|                         |     |
|-------------------------|-----|
| Requires authentication | Yes |
| Has restricted scope    | No  |

**Error codes**

|       |         |                               |
|-------|---------| ----------------------------- |
| `400` | `1000`  | Referenced resource not found |

+ Request
    + Headers

            Authorization: JWT <token>

+ Response 200 (application/json)
    + Attributes (Category)

+ Response 404

# Data Structures

## OAuth grant request (object)
+ `grant_type`: `client_credentials` (string, required)

## OAuth bearer grant request (object)
+ `grant_type`: `urn:ietf:params:oauth:grant-type:jwt-bearer` (string, required)
+ assertion: `eyJhbGciOiJIUzI1NiJ9.e30.XmNK3GpH3Ys_7wsYBfq4C3M6goz71I7dTgUkuIa5lyQ` (string, required)

## OAuth valid response (object)
+ `access_token`: `eyJhbGciOiJIUzI1NiJ9.e30.XmNK3GpH3Ys_7wsYBfq4C3M6goz71I7dTgUkuIa5lyQ` (string, required) - valid JWT
+ scope: all (string, required) - scopes of current token
+ `expires_in`: 300 (number, required)
+ `token_type`: Bearer (string, required)

## Server response (object)
+ status: ok (string, required)

## Resource (object)
+ id: `a6vhAo3FG7t1` (string, fixed) - Short non-sequential url-friendly unique id.
+ createdAt: `2016-07-01T15:11:09.553Z` (string) - When this resource was created.
+ updatedAt: `2016-07-01T15:11:09.553Z` (string) - When this resource was last updated.

## User (Resource)
+ email: `john.doe@mail.com` (string, required) - Unique email address of the user.
+ username: `johndoe` (string, required) - Username
+ name: `John` (string, optional, nullable) - First name of the user.
+ surname: `Doe` (string, optional, nullable) - Last name of the user.
+ avatar (string, optional, nullable) - URL to user avatar.
+ user_level: user (string, required) - User level

## Agency (User)
+ `company_name`: `Magespecialist` (string, required) - Agency business name
+ logo: `https://www.magespecialist.it/wp-content/uploads/logo_magesepcialist_header.png` (string, optional, nullable) - URL to company logo.
+ website: `https://www.magespecialist.it` (string, required) Agency website URL
+ description: `Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.` (string, optional, nullable) - Agency brief description
+ user_level: agency (string, required) - User level

## Referee (User)
+ user_level: referee (string, required) - User level

## Vote (Resource)
+ vote: 73 (number, required) Vote rating
+ date: `2016-07-01T15:11:09.553Z` (string) - Vote timestamp.
+ user (Referee)

## Category (Resource)
+ title: `Web/App` (string, required) - category title
+ stub: `web` (string, required) - category stub
+ project_count: 42 (number) - project count

## Tag (Resource)
+ title: `video` (string, required) - tag title
+ stub: `video` (string, required) - tag stub
+ project_count: 13 (number) - project count

## Screenshot (Resource)
+ title: `Page` (string, required) - Image title
+ filename: `logo_magesepcialist_header.png` (string, required) - Image filename
+ url: `https://www.magespecialist.it/wp-content/uploads/logo_magesepcialist_header.png` (string, required) - Image URL

## Project (Resource)
+ title: `Astonishing Project` (string, required) - project title
+ description: `Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?` (string, required) - project HTML description
+ agency (Agency)
+ category (Category)
+ tags (array[Tag])
+ screenshots (array[Screenshot])
+ video: `https://player.vimeo.com/video/217499569?portrait=0&badge=0` (string) - the embed video URL
+ referee_rating: `86.5` (number, optional, nullable) - referees average votes
+ user_rating: `79.5` (number, optional, nullable) - users average result
+ total_rating: `81.5` (number, optional, nullable) - current result
+ vote_expiration: `2016-07-01T15:11:09.553Z` (string) - When the project vote will expire.
+ archived_from: `2016-07-01T15:11:09.553Z` (string) - When the project has been archived.
+ dow_award: `2016-07-01T15:11:09.553Z` (string) - If the project has received won the DOW award, this is the award date.
+ special_award: `2016-07-01T15:11:09.553Z` (string) - If the project has received the special award, this is the award date.
+ vote_list (array[Vote])