apiary.apib

FORMAT: 1A

# Payback API
Payback API is a service to track and optimize debts between a group of friends.

## Authentication
Currently the Payback API does not provide authenticated access.
Authentication will be implemented using OAuth, with logins by username and password, Facebook, Google and other services.

## Digital Signature
To prevent tampering of the data, a digital signature is included as a header in every request.
The header name is X-Checksum and it is calculated using HMAC-SHA1 of the JSON representation of an object
including url, query parameters and request body.

## Media Types
Where applicable this API uses the JSON media-type to represent resources states and affordances.

Requests with a message-body are using plain JSON to set or update resource states.

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

# Payback API Root [/]
Payback API entry point.

This resource does not have any attributes.

## Retrieve the Entry Point [GET]

+ Response 204

# Group User
Users related resources of the **Payback API**

## User [/users/{id}]
A single User object. The User resource is the central resource in the Payback API. It represents one user of the service.

The User resource has the following attributes:

- id -- Username of the User
- email -- Email of the User

+ Parameters
    + id (string, required, `john`) ... ID of the User

+ Model (application/json)

    ```js
    {
        "id": "johndoe",
        "email": "johndoe@example.com"
    }
    ```

### Retrieve a single User [GET]
This method is only available for the authenticated user.

+ Response 200 (application/json)

    [User][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist." }

### Update a single User [PATCH]
This method is only available for the authenticated user.
*email* is the only modifiable field.

+ Request (application/json)

        {
            "email": "newemail@example.com"
        }

+ Response 200 (application/json)

    [User][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Cannot update field 'whatever'" }
        or
        { "error": "Invalid checksum" }
        or
        { "error": "Email 'john@example.com' already exists." }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist." }

### Delete a User [DELETE]
This method is only available for the authenticated user.

+ Response 204

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist." }

## Debt [/users/{id}/debts/{debtId}{?currency}]
A single Debt object. The Debt resource represents a debt that a User has on another User.

A positive *value* means that this User owes something to another User, a negative *value* means that this User is owed by another User.

The Debt resource has the following attributes:

- debtId -- Id of a Debt of a User (read-only)
- creditor -- User that credits the debt (read-only)
- debtor -- User that owes the creditor (read-only)
- originalValue -- Money that we owe or are owed by the User above (read-only)
- value -- Money that we owe or are owed by the User above
- currency -- Money currency of the value (read-only)
- created -- Date (ISO 8601) the Debt was created (read-only)
- modified -- Date (ISO 8601) the Debt was last modified (read-only, not const)

+ Parameters
    + id (string, required, `john`) ... ID of the User
    + debtId (number, required, `1`) ... ID of the Debt of a User

+ Model (application/json)

    ```js
    {
        "debtId": 1,
        "creditor": "john",
        "debtor": "janeroe",
        "originalValue": 100,
        "value": 0,
        "currency": "EUR",
        "created": "2014-04-14T11:29Z",
        "modified": "2014-04-15T09:10Z"
    }
    ```

### Retrieve a single Debt [GET]
This method is only available for the authenticated user.

+ Parameters
    + currency (string, optional, `EUR`) ... Currency

+ Response 200 (application/json)

    [Debt][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "Debt '2' for user 'johndoe' does not exist." }

### Update a single Debt [PATCH]
This method is only available for the authenticated user.
The only modifiable field is *value*.

+ Request (application/json)

        {
            "value": 0,
            "currency": "EUR"
        }

+ Response 200 (application/json)

    [Debt][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Cannot update field 'whatever'" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "Debt '2' for user 'johndoe' does not exist." }

### Delete a Debt [DELETE]
This method is only available for the authenticated user.

+ Response 204

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "Debt '2' for user 'johndoe' does not exist." }

## Debts Collection [/users/{id}/debts{?currency}]
Collection of all Debts that another User owes this User.

The Debts Collection resource has the following attribute:

- total -- Total number of Debts
- balance -- Total balance between owed money
- credit -- Money owed to this User
- debit -- Money that this User owes to the other Users
- currency -- Currency of *balance*, *debit* and *credit*
- debts -- Array of Debts

+ Parameters
    + id (string, required, `john`) ... ID of the User

+ Model (application/json)

    ```js
    {
        "total": 2,
        "balance": -3.4,
        "credit": 0,
        "debit": 3.4,
        "currency": "EUR",
        "debts":
        [
            {
                "debtId": 1,
                "creditor": "john",
                "debtor": "janeroe",
                "originalValue": 100,
                "value": 0,
                "currency": "EUR",
                "created": "2014-04-14T11:29Z",
                "modified": "2014-04-15T09:10Z"
            },
            {
                "debtId": 2,
                "creditor": "smith",
                "debtor": "john",
                "user": "smith",
                "originalValue": 5.4,
                "value": 3.4,
                "currency": "EUR",
                "created": "2014-04-16T08:30Z",
                "modified": "2014-04-17T10:30Z"
            }
        ]
    }
    ```

### List all Debts of a User [GET]
This method is only available for the authenticated user.

+ Parameters
    + currency (string, optional, `EUR`) ... Currency

+ Response 200 (application/json)

    [Debts Collection][]
    
+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

### Create a new Debt [POST]
This method is only available for the authenticated user.

+ Request (application/json)

        {
            "user": "johndoe",
            "value": 100,
            "currency": "EUR"
        }

+ Response 201 (application/json)

        {
            "created": [
                {
                    "debtId": 2,
                    "creditor": "smith",
                    "debtor": "john",
                    "user": "smith",
                    "originalValue": 5.4,
                    "value": 3.4,
                    "currency": "EUR",
                    "created": "2014-04-16T08:30Z",
                    "modified": "2014-04-17T10:30Z"
                }
            ],
            "updated": [
                {
                    "debtId": 1,
                    "creditor": "john",
                    "debtor": "janeroe",
                    "originalValue": 100,
                    "value": 0,
                    "currency": "EUR",
                    "created": "2014-04-14T11:29Z",
                    "modified": "2014-04-15T09:10Z"
                }
            ]
        }

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist." }
        or
        { "error": "Value '0.0001' is invalid." }

## Friend [/users/{id}/friends/{friendId}]
A single Friend object. The Friend resource represents a friend of a User.

The Friend resource has the following attributes:

- id -- Username of a Friend

+ Parameters
    + id (string, required, `john`) ... ID of the User
    + friendId (string, required, `jane`) ... ID of a Friend of a User

+ Model (application/json)

    ```js
    {
        "id": "johndoe"
    }
    ```

### Retrieve a single Friend [GET]
This method is only available for the authenticated user.

+ Response 200 (application/json)

    [Friend][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist or is not a friend." }

### Delete a single Friend [DELETE]
This method is only available for the authenticated user.

+ Response 204

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist or is not a friend." }

## Friends Collection [/users/{id}/friends]
Collection of all Users that are Friends of a User.

This is a one-way only friendship and it is used to provide quick access to Users that are commonly used in the transactions.

The Friends Collection resource has the following attributes:

- total -- Total number of Friends
- friends -- Array of Friends (not detailed)

+ Parameters
    + id (string, required, `john`) ... ID of the User

+ Model (application/json)

    ```js
    {
        "total": 2,
        "friends": 
        [
            { "id": "janeroe" },
            { "id": "smith" }
        ]
    }
    ```

### List all Friends of a User [GET]
This method is only available for the authenticated user.

+ Response 200 (application/json)

    [Friends Collection][]

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

### Create a Friend of a User [POST]
This method is only available for the authenticated user.

+ Request (application/json)

        { "id": "johndoe" }

+ Response 201 (application/json)

        { "id": "johndoe" }

+ Response 403 (application/json)

        { "error": "User 'johndoe' already friended." }
        or
        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

+ Response 404 (application/json)

        { "error": "User 'johndoe' does not exist." }

### Delete all Friends of a User [DELETE]
This method is only available for the authenticated user.

+ Response 204

+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

## Users Collection [/users{?search}]
Collection of all Users.

The User Collection resource has the following attributes:

- total -- Total number of Users
- Users -- Array of Users (not detailed)

### List all Users [GET]
+ Parameters

    + search (string, optional, `jo`) ... Fuzzy search. Only users that have an *id* or *email* related to the *search* parameter are returned.

+ Response 200 (application/json)

        {
            "total": 2,
            "users": 
            [
                { "id": "johndoe" },
                { "id": "janeroe" }
            ]
        }
        
+ Response 403 (application/json)

        { "error": "No permission" }
        or
        { "error": "Invalid checksum" }

### Create a User [POST]

+ Parameters

    + search (string, optional, `jo`) ... Fuzzy search. Only users that have an *id* or *email* related to the *search* parameter are returned.

+ Request (application/json)

        { "id": "john", "email": "john@example.com", "passwordHash": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd" }

+ Response 201 (application/json)

        { "id": "john", "email": "john@example.com" }

+ Response 403 (application/json)

        { "error": "User 'john' already exists." }
        or
        { "error": "Email 'john@example.com' already exists." }
        or
        { "error": "Invalid checksum" }

## Exchange Rates Collection [/exchangeRates]
Collection of all exchange rates.

The Exchange Rates resource has the following attributes:

- base -- Currency used as base for the rates
- rates -- Exchange rates

+ Model (application/json)

    ```js
    {
        "base": "EUR",
        "rates": {
            "AUD": 1.4684,
            "BGN": 1.9558,
            "BRL": 3.0485,
            "CAD": 1.4976,
            "CHF": 1.2211
        }
    }

### List all Exchange Rates [GET]

+ Response 200 (application/json)

    [Exchange Rates Collection][]