Linkboards (1.0.0)

Download OpenAPI specification:Download

An API for sharing links. Users can create link boards and invite other users to join them. Links can be posted to boards, users can rate and discover them using queries.

Authentication

BearerAuth

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Boards

Create a new board

Creates a new board. The creating user will have the "owner" role. A board can have at most 32 users.

Authorizations:

BearerAuth

Request Body schema: application/json

name required	string [ 1 .. 100 ] characters
description	string <= 1000 characters

Responses

Request samples

Payload

Content type

application/json

{"name": "Example board",
"description": "This is a description."
}

Response samples

201
400

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"name": "Best board ever",
"description": "Just a description, nothing to see here.",
"createdTime": "1665570512173963500,",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"modifiedTime": "1665570512173963500,",
"modifiedBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"users": [{"user": {"userId": "u-1234-5678",
"name": "John Doe"
},
"role": "owner",
"createdTime": 1665570512173963500,
"invitedBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"modifiedTime": 1665570512173963500,
"modifiedBy": {"userId": "u-1234-5678",
"name": "John Doe"
}
}
],
"invites": [{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"inviteId": "i-55067be9-62a4-4861-8bbe-9e8382dd9751",
"role": "owner",
"user": {"userId": "u-3921-5901",
"name": "Testi Tester"
},
"createdTime": 1665570512173963500,
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"expiresTime": 1665570512173963500
}
]
}

Get boards

Returns boards the user making the request is part of. Results are sorted by the time the user joined the board, i.e. newer ones first. Since the number of results might be large, the query can be paginated.

Authorizations:

BearerAuth

query Parameters

limit	integer Maximum number of results to return
cursor	integer <int64> Return only boards the user joined at or before the given Unix time (in nanoseconds)

Responses

Response samples

200

Content type

application/json

[{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"name": "Best board ever",
"description": "Just a description, nothing to see here.",
"createdTime": "1665570512173963500,",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
}
}
]

Delete a board

Authorizations:

BearerAuth

path Parameters

boardId

required

string

Responses

Get a board

Returns the board with the given id. The board's users and invites will only be included if the user making the request has an authorized role.

Authorizations:

BearerAuth

path Parameters

boardId

required

string

Responses

Response samples

200

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"name": "Best board ever",
"description": "Just a description, nothing to see here.",
"createdTime": "1665570512173963500,",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"modifiedTime": "1665570512173963500,",
"modifiedBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"users": [{"user": {"userId": "u-1234-5678",
"name": "John Doe"
},
"role": "owner",
"createdTime": 1665570512173963500,
"invitedBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"modifiedTime": 1665570512173963500,
"modifiedBy": {"userId": "u-1234-5678",
"name": "John Doe"
}
}
],
"invites": [{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"inviteId": "i-55067be9-62a4-4861-8bbe-9e8382dd9751",
"role": "owner",
"user": {"userId": "u-3921-5901",
"name": "Testi Tester"
},
"createdTime": 1665570512173963500,
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"expiresTime": 1665570512173963500
}
]
}

Edit board

Authorizations:

BearerAuth

path Parameters

boardId

required

string

Request Body schema: application/json

name	string [ 1 .. 100 ] characters
description	string <= 1000 characters

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string"
}

Response samples

200
400

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"name": "Best board ever",
"description": "Just a description, nothing to see here.",
"createdTime": "1665570512173963500,",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
}
}

Create a new invite

Creates a new invite for the given board. If a user is provided in the request, only that user will be able to accept the invite, otherwise any user can. Note that an invite cannot be created if the board is full or the invite is for a user that is already part of the board. The number of users and invites per board is limited to 32.

Authorizations:

BearerAuth

path Parameters

boardId

required

string

Request Body schema: application/json

role required	string (role) Enum: "owner" "viewer" "editor"
	object (user)

Responses

Request samples

Payload

Content type

application/json

{"role": "owner",
"user": {"userId": "u-1234-5678",
"name": "John Doe"
}
}

Response samples

201
400

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"inviteId": "i-55067be9-62a4-4861-8bbe-9e8382dd9751",
"role": "owner",
"user": {"userId": "u-1234-5678",
"name": "John Doe"
},
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"expiresTime": "1665570512173963452"
}

Accept/Decline an invite

An invite can only be declined by a user if it was created for that user.

Authorizations:

BearerAuth

path Parameters

boardId required	string
inviteId required	string

Request Body schema: application/json

response

required

string

Enum: "accept" "decline"

Responses

Request samples

Payload

Content type

application/json

{"response": "accept"
}

Response samples

400

Content type

application/json

{"error": {"code": 42,
"message": "Invalid request"
}
}

Delete an invite

Authorizations:

BearerAuth

path Parameters

boardId required	string
inviteId required	string

Responses

Get invites

Returns invites for the user making the request, sorted by the time the invite was created, i.e. newest invites first. Since the number of results might be large, the query can be paginated.

Authorizations:

BearerAuth

query Parameters

limit	integer Maximum number of results to return
cursor	integer <int64> Return only invites created at or before the given Unix time (in nanoseconds)

Responses

Response samples

200

Content type

application/json

[{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"inviteId": "i-55067be9-62a4-4861-8bbe-9e8382dd9751",
"role": "owner",
"user": {"userId": "u-1234-5678",
"name": "John Doe"
},
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"expiresTime": "1665570512173963452"
}
]

Remove a user from a board

Note that the board owner cannot be removed.

Authorizations:

BearerAuth

path Parameters

boardId required	string
userId required	string

Responses

Response samples

400

Content type

application/json

{"error": {"code": 42,
"message": "Invalid request"
}
}

Edit a user of a board

Can be used to change the role a user has on the board.

Authorizations:

BearerAuth

path Parameters

boardId required	string
userId required	string

Request Body schema: application/json

role

required

string

Enum: "editor" "viewer"

Responses

Request samples

Payload

Content type

application/json

{"role": "editor"
}

Response samples

200
400

Content type

application:json

{"user": {"userId": "u-1234-5678",
"name": "John Doe"
},
"role": "owner",
"createdTime": "1665570512173963452",
"invitedBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"modifiedTime": "1665570512173963452",
"modifiedBy": {"userId": "u-1234-5678",
"name": "John Doe"
}
}

Links

Create link

Creates a new link on the given board.

Authorizations:

BearerAuth

path Parameters

boardId

required

string

Request Body schema: application/json

title required	string [ 1 .. 100 ] characters
url required	string must use "https" scheme

Responses

Request samples

Payload

Content type

application/json

{"title": "Greatest link ever",
"url": "https://example.com/awesomestuff.png"
}

Response samples

201
400

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"linkId": "l-7765378e-3592-47e6-b89e-fd12a0fdf8d2",
"title": "The greatest link ever shared",
"url": "https://example.com/awesomestuff.png",
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"score": 0,
"upvotes": 0,
"downvotes": 0,
"userRating": -1
}

Query links

Query links on the board, results are paginated.

Authorizations:

BearerAuth

query Parameters

limit	integer Maximum number of results to return
sort	string Default: "newest" Enum: "newest" "top" Order of results
cursorScore	integer Return only links with less than or with score
cursorCreatedTime	integer <int64> Return only links created at or before the given Unix time (in nanoseconds)

Responses

Response samples

200

Content type

application/json

[{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"linkId": "l-7765378e-3592-47e6-b89e-fd12a0fdf8d2",
"title": "The greatest link ever shared",
"url": "https://example.com/awesomestuff.png",
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"score": 0,
"upvotes": 0,
"downvotes": 0,
"userRating": -1
}
]

Get a link

Authorizations:

BearerAuth

path Parameters

boardId required	string
linkId required	string

Responses

Response samples

200

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"linkId": "l-7765378e-3592-47e6-b89e-fd12a0fdf8d2",
"title": "The greatest link ever shared",
"url": "https://example.com/awesomestuff.png",
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"score": 0,
"upvotes": 0,
"downvotes": 0,
"userRating": -1
}

Delete a link

Authorizations:

BearerAuth

path Parameters

boardId required	string
linkId required	string

Responses

Rate a link

Update/create a link rating. The only valid ratings are -1 (downvote) and 1 (upvote).

Authorizations:

BearerAuth

path Parameters

boardId required	string
linkId required	string

Request Body schema: application/json

rating

required

integer

Enum: -1 1

-1 for downvote, 1 for upvote

Responses

Request samples

Payload

Content type

application/json

{"rating": -1
}

Response samples

200
400

Content type

application/json

{"boardId": "b-55067be9-62a4-4861-8bbe-9e8382dd9751",
"linkId": "l-7765378e-3592-47e6-b89e-fd12a0fdf8d2",
"title": "The greatest link ever shared",
"url": "https://example.com/awesomestuff.png",
"createdTime": "1665570512173963452",
"createdBy": {"userId": "u-1234-5678",
"name": "John Doe"
},
"score": 0,
"upvotes": 0,
"downvotes": 0,
"userRating": -1
}