# 請求方式說明

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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.firstline.cc/developer/api/request-methods.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.