# 請求方式說明

FIRST LINE 採用 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) 為主設計 API，而使用到的 HTTP 請求方法共有四種方式：

| 方法         | 描述                |
| ---------- | ----------------- |
| **GET**    | 請求展示指定資源，即瀏覽資料    |
| **POST**   | 用於提交指定資源的實體，即新增資料 |
| **PUT**    | 取代指定資源，即更新資料      |
| **DELETE** | 刪除指定資源，即刪除資料      |

## 請求示範例

下方為使用 `POST` 請求新增一個客戶的 postman 示意範例

```javascript
{
    "membership_no":"R0000555",
    "identity_no":"A000000002",
    "gender":0,
    "first_name":"陳",
    "last_name":"大華",
    "birth_at":"1990-01-01"
}
```

{% hint style="info" %}
在 Postman 中，建議使用 Body 選擇「raw」並直接輸入JSON。這樣可以避免 Postman 誤將數值轉換為字串，進而防止某些欄位在驗證時出現錯誤。
{% endhint %}

![](https://developers.firstline.cc/images/post_example_1.png)

###

### 表頭

![](https://developers.firstline.cc/images/post_example_2.png)

表頭的部分有三個，下面逐一解釋:

| **表頭**            | 描述                                         |
| ----------------- | ------------------------------------------ |
| **Authorization** | 即 token，亦可使用 query string parameter 替代。    |
| **Content-Type**  | 確保伺服器接收和回傳都會以 json 形式處理，因此這表頭是必要的。         |
| **Accept**        | 為了確保 server 端接收和回傳都會以 json 形式處理，因此這表頭是必要的。 |

```javascript
{
    "Authorization":"YOUR_TOKEN",
    "Content-Type": "application/json",
    "Accept":"application/json",
}
```

## 其他方法

### GET \ DELETE

`GET`，`DELETE` 依此類推，選用對應的 postman 請求方法即可。

### PUT 

因不支持直接使用 Http PUT 請求。所以，當需要進行PUT請求的時候，請使用POST方法替代，並確保附加\_method="put"這一參數。

![Postman 示意圖](https://developers.firstline.cc/images/put_example.png)

```javascript
{
    "membership_no":"R0000567",
    "identity_no":"A000000001",
    "gender":0,
    "first_name":"王",
    "last_name":"小明",
    "birth_at":"1999-09-09"
}
```

## 錯誤代碼

採用標準 HTTP 狀態碼，由 [RFC 2616](https://tools.ietf.org/html/rfc2616) 規範定義的，並得到 [RFC 2518](https://tools.ietf.org/html/rfc2518)、[RFC 2817](https://tools.ietf.org/html/rfc2817)、[RFC 2295](https://tools.ietf.org/html/rfc2295)、[RFC 2774](https://tools.ietf.org/html/rfc2774) 與 [RFC 4918](https://tools.ietf.org/html/rfc4918) 等規範擴充。所有狀態碼被分為五類，狀態碼的第一個數字代表了回應的五種狀態之一。所示的訊息短語是典型的，但是可以提供任何可讀取的替代方案。 除非另有說明，狀態碼是HTTP/1.1標準（[RFC 7231](https://tools.ietf.org/html/rfc7231)）的一部分。

<table data-header-hidden><thead><tr><th width="145">代碼</th><th>敘述</th></tr></thead><tbody><tr><td>代碼</td><td>敘述</td></tr><tr><td>400</td><td>Bad Request - Your request is invalid.</td></tr><tr><td>401</td><td>Unauthorized -- Your API key is wrong.</td></tr><tr><td>403</td><td>Forbidden -- The kitten requested is hidden for administrators only.</td></tr><tr><td>404</td><td>Not Found -- The specified kitten could not be found.</td></tr><tr><td>405</td><td>Method Not Allowed -- You tried to access a kitten with an invalid method.</td></tr><tr><td>406</td><td>Not Acceptable -- You requested a format that isn't json.</td></tr><tr><td>410</td><td>Gone -- The kitten requested has been removed from our servers.</td></tr><tr><td>418</td><td>I'm a teapot.</td></tr><tr><td>419</td><td>Sesstion expired.</td></tr><tr><td>422</td><td>Unprocessable Entity.</td></tr><tr><td>429</td><td>Too Many Requests -- You're requesting too many kittens! Slow down!</td></tr><tr><td>500</td><td>Internal Server Error -- We had a problem with our server. Try again later.</td></tr><tr><td>503</td><td>Service Unavailable </td></tr></tbody></table>