---
# System prepended metadata

title: API design

---

# API design

## Data Types

ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON

- string
- number
- object
- an array
- boolean

if optional append '?' at end, e.g. string?

## Global Exceptions

[401] 尚未登入
```javascript=
{
    message: 'Unauthorized'
}
```

[403] 已登入但權限不足
```javascript=
{
    message: 'Forbidden'
}
```

[400] 尚未啟動
```javascript=
{
    message: 'Unactivate'
}
```

## Authentication

### 登入

POST /api/auth/login

request body payload
```javascript=
{
    account: 'kellly',   // string
    password: '12345678' // string
}
```

[200] success
```javascript=
{
    accessToken: 'your_access_token' // string
}
```
[400] 帳號密碼錯誤
```javascript=
{
    message: 'Bad request' // string
}
```

## Activate

### 傳送啟動碼

POST /api/activate

request body payload
```javascript=
{
    serial: '1111-2222-3333-4444' // string
}
```

[200] success
```javascript=
{
    message: 'Activate Success!' // string
}
```
[400] error
```javascript=
{
    message: 'Activate Failed!' // string
}
```

## Users

[GET] /api/users

RESTful

![](https://i.imgur.com/MhGcJIe.png)

[200] success
```javascript=
{
    message: 'OK',
    data: [
        {
            account: 'kellly',                            // string
            lastModifierTime: "2022-12-13T13:16:56.007Z", // string?
            role: 'admin',                                // string
            active: true                                  // bool
        },
        {
            account: 'kellly',
            lastModifierTime: "2022-12-13T13:16:56.007Z",
            role: 'admin',
            active: true
        },
    ]
}
```

[204] no data
```javascript=
{
    message: 'ok',
    data: []
}
```

# Create User

[POST] /api/users

payload
```javascript
{
    account: 'kelly',
    password: '12345678',
    active: true,
    permissions: {
    }
}
```

[200]
```javascript=
{
    message: 'ok',
}
```

[400]
```javascript=
{
    message: 'need password',
}
```

[401]
```javascript=
{
    message: 'unauthorized',
}
```

[403]
```javascript=
{
    message: 'forbidden',
}
```

# Update User

[POST] /api/users/:account

payload
```javascript
{
    password: '',
    active: true,
    permissions: {
    }
}
```

[200]
```javascript=
{
    message: 'ok',
}
```

[401]
```javascript=
{
    message: 'unauthorized',
}
```

[403]
```javascript=
{
    message: 'forbidden',
}
```


![](https://i.imgur.com/fT0KdcJ.png)
