Sinker API

The Sinker API is a small API to store centralized state for the Sinker executable, so that multiple devices from the same user can share the same files.

Usage

The API provides 2 endpoints to store file events, and fetch the latest from a given timestamp.

Store Event

You can store an event with:

POST /api/v1/events

And the following body:

{
    "type": "CREATE",
    "path": "path/to/your/file.txt"
}

The following validation rules are enforced:

type: required, must be one of CREATE, REMOVE, and WRITE
path: required, must be a string of max 255 characters. This is the relative path of the file being synchronized

The following response is returned:

{
    "data": {
        "id": 1,
        "type": "CREATE",
        "path": "path/to/your/file.txt"
    }
}

Please note: this will remove all previous events related to that path.

Latest Events

GET /api/v1/events/latest?t=1600000000

The timestamp t must be a valid UNIX timestamp.

The following response is returned:

{
    "data": [
        {
            "id": 1,
            "type": "CREATE",
            "path": "path/to/your/file.txt"
        }
    ]
}

Please note: this will not return events generated by the same device that is making the request

Development

Requirements

PHP 8.0: you can install it on macOS via Homebrew: brew install php@8.0
Composer
Postgresql 13: you can install it on macOS via Homebrew brew install postgres@13

Setup

If you've never developed the Sinker API, make sure to start by creating the databases (development and test):

php artisan db:create sinker_api_development
php artisan db:create sinker_api_test

Then, migrate the database:

php artisan migrate

And start the local dev server:

php artisan serve

Tests

You can run the whole CI pipeline by running composer run-script ci

Otherwise you can:

Lint (using PHP CS Fixer): composer run-script check-style
Run stan (using Psalm): composer run-script stan
Run tests (using PHPUnit): composer run-script test

thtg88 / sinker-api