teamboard-api
is the API Teamboard uses.
The API depends on having MongoDB and Redis up and running.
npm install N4SJAMK/teamboard-api
Set NODE_ENV
to development
for local development, assuming you have
development dependencies installed locally. If you are running in production
environment, you must specify the required environmental variables. There is
also a test
environment that is used for test runs.
MONGODB_URL
is actually the connection string passed tomongoose
, for example:mongodb://localhost:27017/teamboard-dev
.REDIS_HOST
andREDIS_PORT
corresponding to your runningredis-server
.TOKEN_SECRET
is the secret used withjsonwebtoken
.
You can also specify the PORT
variable to change the default port of 9002
.
Once you've set the required variables, run:
npm start
npm test
All the API methods except /auth/login
and /auth/register
expect that the
Authorization
header is set to Bearer access-token
where access-token
is
the x-access-token
received from providing correct credentials. Failure to
provide a proper access-token
will be met with a swift 401.
GET /auth
returns:
{
"id": "id"
"type": "user | guest",
"username": "email | username",
}
Returns the user
object tied to access-token
passed in Authorization
header. If the user's type
is guest
, access
field will also be present in
the response containing the id
of the board
the token is tied to.
POST /auth/login
payload:
{
"email": "email",
"password": "password"
}
returns:
{
"id": "id",
"type": "user",
"username": "email"
}
Exchanges the given credentials for an access-token
. The access-token
is
returned in the x-access-token
header. The type
of the token received from
this method is always user
.
POST /auth/register
payload:
{
"email": "email",
"password": "password"
}
returns:
{
"id": "id",
"email": "email"
}
Creates a new user.
POST /auth/logout
Removes the given token from the matching user, essentially logging the user out.
GET /boards
returns:
[
{
"id": "id",
"name": "name",
"description": "description",
"createdBy": "user.id",
"accessCode": "",
"background": "none",
"size": {
"width": 8,
"height": 8
}
}
]
Returns an array of boards
that are created by the user
identified by the
given access-token
.
GET /boards/:id
Returns the board
object specified by :id
. See above for the description of
the board
object.
POST /boards
payload:
{
"name": "name"
}
Creates a new board with the given name
. See above for a list of properties
that a board
can have. Returns the created board
object, see above for the
description of the board
object.
PUT /boards/:id
payload:
{
"description": "new description"
}
Updates the board specified by :id
. See above for possibilities. Returns the
updated board
object. See above for the description of the board
object.
DELETE /boards/:id
Removes the board specified by :id
. Returns the removed board
object. See
above for the description of the board
object.
GET /boards/:id/tickets
returns:
[
{
"id": "id",
"content": "content",
"color": "#BABABA",
"position": {
"x": 0, "y": 0
}
}
]
Returns an array of ticket
objects that belong to the board
specified by
:id
.
POST /boards/:id/tickets
payload:
{
"content": "content"
}
Creates a new ticket
. Returns the created ticket
object. See above for the
description of ticket
object.
PUT /boards/:id/tickets/:id
payload:
{
"content": "new-content"
}
Updates a ticket specified by :id
. Returns the updated ticket
object. See
above for the description of the ticket
object.
DELETE /boards/:id/tickets/:id
Removes the ticket specified by :id
. Returns the removed ticket
object. See
above for the description of the ticket
object.
Comments are actually events, see below for an explanation.
GET /boards/:id/tickets/:id/comments
returns:
[ EventObject ]
POST /boards/:id/tickets/:id/comments
payload:
{
'comment': '...',
}
returns:
{ EventObject }
Events are generated for various actions done via the API. Events are also
emitted through teamboard-io
, so that connected clients can listen to them
under the key board:event
.
Currently the possible event types
are:
BOARD_CREATE
,BOARD_EDIT
,BOARD_REMOVE
BOARD_PUBLISH
,BOARD_UNPUBLISH
,BOARD_GUEST_JOIN
TICKET_CREATE
,TICKET_EDIT
,TICKET_REMOVE
, 'TICKET_COMMENT'
The returned events
have a data
field that is used to store additional data
regarding the event
. For example for ticket based events this usually means
storing an id
attribute referencing the ticket in question.
GET /boards/:id/events
returns:
[{
'type': 'event.type',
'board': 'board.id',
'user': { 'id', 'type', 'username' },
'data': { }
}]
Guest access can be granted to a board by generating an access-code
for it.
By using this access-code
anonymous users can request an access-token
that
is tied to a specific board and to the specific access-code
.
POST /boards/:id/access
returns:
{
"accessCode": "123ABCDE"
}
Generates an access-code
for the board specified by :id
. Successive calls
to this method will always generate a new access-code
, thus invalidating any
access-tokens
that were tied to the previous access-code
.
DELETE /boards/:id/access
Removes the access-code
of the board specified by :id
, invalidating any
access-tokens
tied to it.
POST /boards/:id/access/:code
payload:
{
"username": "username"
}
returns:
{
"id": "id",
"type": "guest",
"access": "board.id",
"username": "username"
}
Requests an access-token
for the board
specified by :id
and authorized by
:code
. The access token can be found in x-access-token
after a succesful
request. The method also returns the payload encoded in the access-token
.