🚧 This is work in progress

---

🌲 piny.link

API server for tiny bookmarking service

Requirements

• node 24.x

Quick start

Install dependencies:

npm install

Create empty database:

npm -w @piny/db run sync

Start dev server:

KEY="secret-key" npm -w @piny/api run dev

Production:

KEY="secret-key" npm -w @piny/api start

API

This doc assume that your server running on https://dev.piny.link. The request examples uses httpie.

Emoji key:

• 🌍 Public endpoint
• 🔐 Requires authorisation

Headers:

• Content-Type: application/json — default body type
• Authorization: Bearer XXX — replace XXX with token from /login response (🔐 restricted endpoints only)

🌍 Create user

POST /signup

Body

• user: string — user name (unique)
• pass: string — user password (no restrictions)
• email: string — user email (unique)

Request

http --json POST 'https://dev.piny.link/signup' \
'Content-Type':'application/json' \
user="foo" \
pass="1234" \
email="foo@bar.baz"

Response

201

{
"message": "👋 Welcome, please /login"
}

🌍 Log in

POST /login

Body

• user: string — user name
• pass: string — user password

Request

http --json POST 'https://dev.piny.link/login' \
'Content-Type':'application/json' \
pass="1234" \
user="foo"

Response

200

{
"token": "XXX",
}

🔐 Log out

GET /logout

Request

http GET 'https://dev.piny.link/logout' \
'Authorization':'Bearer XXX'

Response

200

{
"message": "👋 Bye"
}

🔐 Get user

GET /:user

Params

• user: string — user name

Request

http GET 'https://dev.piny.link/:user' \
'Authorization':'Bearer XXX'

Response

200

{
"id": "YYY",
"name": "foo",
"email": "foo@bar.baz"
}

🌍/🔐 Get user bookmarks

GET /:user?/bookmarks

Params

• user?: string — user name (if omitted, get bookmarks of current user)

Request

http GET 'https://dev.piny.link/:user/bookmarks' \
'Authorization':'Bearer XXX'

Response

200

[
{
"id": "ff7b3bb2-5fad-4924-81a6-5bedc3ded3dd",
"title": "KayWay",
"description": "Illustration portfolio by Ekaterina Grishina",
"state": "active",
"privacy": "public",
"link": {
"id": "a6f7584f-c1a5-42e8-bd98-e1bb003fc219",
"url": "https://kayway.me/"
},
"tags": [
{
"id": "2c00e362-30fc-4dba-89ed-24c0a3d11ab4",
"name": "illustrator"
},
{
"id": "823e8339-2296-4972-aeed-951df1826228",
"name": "portfolio"
}
],
"createdAt": "2020-08-02T00:34:45.000Z",
"updatedAt": "2020-08-02T00:34:45.000Z"
},
...
]

🔐 Get user tags

GET /:user?/tags

Params

• user: string — user name

Request

http GET 'https://dev.piny.link/:user/tags' \
'Authorization':'Bearer XXX'

Response

200

[
{
"id": "2c00e362-30fc-4dba-89ed-24c0a3d11ab4",
"name": "illustrator"
},
{
"id": "823e8339-2296-4972-aeed-951df1826228",
"name": "portfolio"
}
]

🔐 Create bookmark

POST /bookmarks

Body

• url: string — bookmark url
• title?: string — bookmark title (optional)
• description?: string — bookmark description (optional)
• privacy: 'public' — access to bookmark (only 'public' supported at the moment)
• tags?: string[] — list of tags that should be assigned to the bookmark, will be added to the user tags (optional)

Request

http --json POST 'https://dev.piny.link/bookmarks' \
'Authorization':'Bearer XXX' \
'Content-Type':'application/json' \
title="KayWay" \
description="Illustration portfolio by Ekaterina Grishina" \
url="https://kayway.me" \
privacy="public" \
tags:="[\"illustrator\",\"portfolio\" ]"

Response

201

{
"message": "✨ Created"
}

🔐 Edit bookmark

PATCH /bookmarks/:id

Params

• id: string — bookmark id

Body

• url?: string — bookmark url (optional)
• title?: string — bookmark title (optional)
• description?: string — bookmark description (optional)
• privacy?: 'public' — access to bookmark (only 'public' supported at the moment) (optional)
• tags?: string[] — list of tags that should be assigned to the bookmark, will be added to the user tags (optional)

Request

http --json PATCH 'https://dev.piny.link/bookmarks/:id' \
'Authorization':'Bearer XXX' \
'Content-Type':'application/json' \
title="KayWay" \
description="Illustration portfolio by Ekaterina Grishina" \
tags:="[\"illustrator\",\"portfolio\" ]"

Response

200

{
"message": "💾 Saved"
}

🔐 Delete bookmark

DELETE /bookmarks/:id

Params

• id: string — bookmark id

Request

http DELETE 'https://dev.piny.link/bookmarks/:id' \
'Authorization':'Bearer XXX'

200

{
"message": "🗑 Removed"
}

---

© Ivan Grishin