第六關 - 旅館預約服務

各組別投稿時間

UI 組投稿區間：8/12(一) 12:00 PM ~ 8/19(一) 12:00 PM
前端組投稿區間：8/19(一) 12:00 PM ~ 8/26(一) 12:00 PM

UI 組注意事項

user story

要幫一間旅館設計訂房流程
不需進行會員註冊，只需填寫姓名、電話、預約起迄時間等三個欄位，就可進行訂房。
這間旅館名稱未訂，旅館老闆請 UI 們幫忙想旅館名稱
重要：這間旅館有六個房間，房間資訊請觀看此連結。

Q&A

Q：房間名稱與資訊不能改嗎？一定要遵循你們的？

A：這六間房間已經寫入到資料庫，前端組可藉由 API 撈取旅館資料，所以房間資訊已固定。

Q：所以旅館名稱可以亂改，例如夕陽旅館、豪華酒店等等？

A：可以，此關的限制只有房間資訊。

functional map

首頁：能看到所有房型，並能點擊任一房型，進入到單一房型頁面觀看更多
單一房型頁面：
- 客戶可以觀看該房型詳細資訊，例如旅館描述、平日價格(一~四)、假日價格(五~日)、checkIn 時間、其他服務，詳細資訊欄位請參考此連結。
- 客戶可以用日曆方式，瀏覽未來 90 天已預約與尚未預約的時段。範例一、範例二
- 客戶在選擇預約日期時，會即時顯示訂房價格總價
- 客戶可以線上訂房，需填寫的欄位有
  - 欄位：姓名、電話、預約起迄
  - 只能預約未來 90 天內的時段
- 若預約失敗，會回傳訊息讓客戶知曉，失敗原因項目如下
  - 預訂 90 天後
  - 預約時間已被人預訂
  - 您預約的是過去時間，例如昨天

------ 分隔線：以下皆為前端組資訊， UI 組可以不用觀看 ------

前端組 - 旅館 API 使用教學

Howdy, 我是乾太 Kantai，我在人間當工程師，這次要來介紹今年度 The F2E for 2019 第六關的 API 使用教學以及注意事項，我覺得很簡單，你也可以。

接下來我會介紹如何串接這些 API，以及串接時你需要注意的眉眉角角，基本上你需要獲得 API_TOKEN，你接下來才能串接這整支 API，目的是為了讓你的資料與其他參賽者的資料有所區隔，所以我們需要聽過 API_TOKEN 來識別你的身份，以達到資料區隔的目的。

申請 API TOKEN

在此之前，你需要先申請你自己帳戶的 API_TOKEN，首先請進入 The F2E 官方網站當中，如果已經註冊的就點選登入，如果尚未註冊的就請先申請帳號吧。

Step 0. 註冊並且登入 The F2E 帳號。

The F2E 官方網站 -> The F2E - 前端修練精神時光屋 | 首頁

The F2E for 2019 - 官方網站 | 首頁

Step 1. 先進入「個人檔案」

Step 2. 再進入「個人資料編輯」

The F2E for 2019 - 官方網站 | 個人檔案

Step 3. 點擊「獲取新 Token」用以獲取新 TOKEN。

Step 4. 再回到「個人資料編輯」的頁面

Step 5. 這時候應該可以看到原本空的 Token 欄位，現在多了一大串字符，那個就是你需要的 Token 了。

The F2E for 2019 - 官方網站 | 編輯個人檔案

測試 API 的好工具 - Postman

Postman 官方網站

在開始使用之前，我會推薦大家使用 Postman 來作為你的 API 測試工具，至於他的使用教學你可以上網 Google。

Postman 官方網站 -> Postman | API Development Environment

如何使用 API TOKEN

在呼叫 API 的時候，只需要在 Headers 當中加入 Authorization 參數，並且將 TOKEN 帶入其中即可，帶入方式為 Bearer {your_token}，舉例來說：

The F2E 網站上所獲得的 TOKEN 為 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 正確的 Value 帶入方式：Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 錯誤的 Value 帶入方式：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Postman 帶入 API_TOKEN

這種呼叫方式我會回傳你兩種格式，如果這個 API_TOKEN 格式是正確的、TOKEN 是存在的，那麼我會回傳你 JSON 資料，而另一種情況是可能格式不正確或者 TOKEN 並不存在，那麼我會回傳你整個網頁的登入表單。

伺服器回傳整個網頁的登入表單

Headers 加上 Accept

那麼這時候問題就來了，為什麼錯誤的是回傳我整個網頁的登入表單，而不是用 JSON 來告訴我錯誤？原因是因為你呼叫時並沒有告訴我應該用什麼格式來回傳你，所以預設是將整個網頁登入表單作為回傳，如果你希望錯誤訊息也用 JSON 格式回傳的話，那麼你必須在 headers 當中再加入一個 accept 參數，這個參數的功能是明確的告訴伺服器你希望獲得指定格式的回傳，而這邊我們將帶入 application/json 用以表示我們希望伺服器回傳給我們的是 JSON 資料。

Postman 帶入 Accept

這時候再呼叫一次同樣的 API，就算發送錯誤格式，你也能正常獲得 JSON 格式的回傳資料。

介紹 HTTP Status Code

有些參賽者在這邊可能會納悶，我要怎麼判斷例外錯誤？如果有錯誤的話，難道只會回傳 message 而已嗎？事實上我們應該要多多善用 HTTP Status Code

科普一下 HTTP Status Code
This is a list of Hypertext Transfer Protocol (HTTP) response status codes. Status codes are issued by a server in response to a client’s request made to the server. It includes codes from IETF Request for Comments (RFCs), other specifications, and some additional codes used in some common applications of the Hypertext Transfer Protocol (HTTP). The first digit of the status code specifies one of five standard classes of responses. The message phrases shown are typical, but any human-readable alternative may be provided. Unless otherwise stated, the status code is part of the HTTP/1.1 standard ( RFC 7231 ).[1]

Wikipedia contributors. (2019, July 6). List of HTTP status codes. In Wikipedia, The Free Encyclopedia. Retrieved 05:41, July 9, 2019, from https://en.wikipedia.org/w/index.php?title=List_of_HTTP_status_codes&oldid=905058519

簡單來說，你必須透過狀態碼來判斷這次的呼叫是成功與否，以上面為例，伺服器除了回傳 message 之外，還有告訴你是 401 的錯誤，以便你做出例外處理機制。

401 Unauthorized

最後

Have fun ;)

前端組 - 旅館 API 說明文件

[GET] 取得所有房型

URL

https://challenge.thef2e.com/api/thef2e2019/stage6/rooms

Response Example Model

Inline Model:

{
    "success" (boolean): 成功與否,
    "item": [
        (RoomItem) 房型資料，陣列
    ]
}

RoomItem:

{
    "id" (string): 房間編號,
    "imageUrl" (string): 圖片網址,
    "normalDayPrice" (integer): 平日價格,
    "holidayPrice" (integer): 假日價格,
    "name" (string): 房間名稱
}

Response Example Value

{
    "success": true,
    "item": [
        {
            "id": "KTLSls3bVUDZVk1Pt0R6tI2xeTzoznrqoWqdxjGzK7FuP1GCAbsHSu6MWdxO2rsU",
            "imageUrl": "https://example.com/wtf.png",
            "normalDayPrice": 1200,
            "holidayPrice": 1199,
            "name": "六角大飯店 - 珍珠拉麵套房"
        }
    ]
}

Parameters

none

[GET] 單一房型細節

URL

https://challenge.thef2e.com/api/thef2e2019/stage6/room/{id}

Response Example Model

{
    "success" (boolean): 成功與否,
    "room": [
        {
            "id" (string): 房間編號,
            "imageUrl" (string): 圖片網址,
            "normalDayPrice" (integer): 平日價格,
            "holidayPrice" (integer): 假日價格,
            "name" (string): 房間名稱,
            "description" (string): 房間詳細說明
        }
    ],
    "booking": {
        "name" (string): 訂房者名稱,
        "tel" (string): 訂房者電話,
        "date" (string): 訂房時間,
    }
}

Response Example Value

{
    "success": true,
    "room": [
		{
		    "id": "KTLSls3bVUDZVk1Pt0R6tI2xeTzoznrqoWqdxjGzK7FuP1GCAbsHSu6MWdxO2rsU",
		    "imageUrl": "https://pgw.udn.com.tw/gw/photo.php?u=https://uc.udn.com.tw/photo/2018/11/08/99/5506834.jpg&x=0&y=0&sw=0&sh=0&sl=W&fw=1050",
		    "normalDayPrice": 1200,
		    "holidayPrice": 1199,
		    "name": "六角大飯店 - 珍珠拉麵套房",
		    "description": "怕"
		}
	],
    "booking": [
        {
            "name": "HELL",
            "tel": "0987654321",
            "date": "2019-08-01"
        }
    ]
}

Parameters

id (string): RoomItem(房型資料) 當中的 id(房間編號)

[POST] 預約房型

URL

https://challenge.thef2e.com/api/thef2e2019/stage6/room/{id}

{id} : RoomItem(房型資料) 當中的 id(房間編號)

POST Parameters 傳送格式 (`application/json`)

name (string): 訂房者名稱
tel (string): 訂房者電話
date[] (string): 訂房日期，格式 Y-m-d

Response Example Model

{
    "success" (boolean): 成功與否,
    "room": {
        "id" (string): 房間編號,
        "imageUrl" (string): 圖片網址,
        "normalDayPrice" (integer): 平日價格,
        "holidayPrice" (integer): 假日價格,
        "name" (string): 房間名稱,
        "description" (string): 房間詳細說明
    },
    "booking": {
        "name" (string): 訂房者名稱,
        "tel" (string): 訂房者電話,
        "date" (string): 訂房時間,
    }
}

Response Example Value

{
    "success": true,
    "room": {
        "id": "KTLSls3bVUDZVk1Pt0R6tI2xeTzoznrqoWqdxjGzK7FuP1GCAbsHSu6MWdxO2rsU",
        "imageUrl": "https://pgw.udn.com.tw/gw/photo.php?u=https://uc.udn.com.tw/photo/2018/11/08/99/5506834.jpg&x=0&y=0&sw=0&sh=0&sl=W&fw=1050",
        "normalDayPrice": 1200,
        "holidayPrice": 1199,
        "name": "六角大飯店 - 珍珠拉麵套房",
        "description": "怕"
    },
    "booking": [
        {
            "name": "HELL",
            "tel": "0987654321",
            "date": "2019-08-01"
        }
    ]
}

[DELETE] 清除所有預約

URL

https://challenge.thef2e.com/api/thef2e2019/stage6/rooms

Response Example Model

{
    "success" (boolean): 成功與否
}

Response Example Value

{
    "success": true
}

Parameters

none

問與答

請問訂房有沒有什麼其他限制？

訂房的格式為 name(string)、tel(string)、date[](string)，比較需要注意的是 date[] 這個欄位，它是陣列，陣列內丟 Y-m-d 的時間，我們舉個例子來說，假如我今天想要訂 2019-08-01 到 2019-08-03 這段時間，那麼你就需要這樣丟：

[
    "2019-08-01",
    "2019-08-02",
    "2019-08-03",
]

ㄟㄟㄟ、我的 API 不管怎麼摳它，它只能查詢(GET)，都沒辦法預約房間(POST)或刪除(DELETE)ㄟ！這個部份可能要請您確認一下您所呼叫的參數，如果您的 URL 是 http://challenge.thef2e.com/... 的話，將會碰到上述狀況，您需要走 https://challenge.thef2e.com/...，透過 HTTPS 來呼叫，就能解決您所碰到的問題了。

第六關 - 旅館預約服務

各組別投稿時間

UI 組注意事項

user story

Q&A

functional map

前端組 - 旅館 API 使用教學

申請 API TOKEN

Step 0. 註冊並且登入 The F2E 帳號。

Step 1. 先進入「個人檔案」

Step 2. 再進入「個人資料編輯」

Step 3. 點擊「獲取新 Token」用以獲取新 TOKEN。

Step 4. 再回到「個人資料編輯」的頁面

Step 5. 這時候應該可以看到原本空的 Token 欄位，現在多了一大串字符，那個就是你需要的 Token 了。

測試 API 的好工具 - Postman

如何使用 API TOKEN

Headers 加上 Accept

介紹 HTTP Status Code

最後

前端組 - 旅館 API 說明文件

目錄

[GET] 取得所有房型

URL

Response Example Model

Response Example Value

Parameters

[GET] 單一房型細節

URL

Response Example Model

Response Example Value

Parameters

[POST] 預約房型

URL

POST Parameters 傳送格式 (application/json)

Response Example Model

Response Example Value

[DELETE] 清除所有預約

URL

Response Example Model

Response Example Value

Parameters

問與答

POST Parameters 傳送格式 (`application/json`)