Q:房間名稱與資訊不能改嗎?一定要遵循你們的?
A:這六間房間已經寫入到資料庫,前端組可藉由 API 撈取旅館資料,所以房間資訊已固定。
Q:所以旅館名稱可以亂改,例如夕陽旅館、豪華酒店等等?
A:可以,此關的限制只有房間資訊。
------ 分隔線:以下皆為前端組 資訊, UI 組可以不用觀看 ------
Howdy, 我是乾太 Kantai,我在人間當工程師,這次要來介紹今年度 The F2E for 2019 第六關的 API 使用教學以及注意事項,我覺得很簡單,你也可以。
接下來我會介紹如何串接這些 API,以及串接時你需要注意的眉眉角角,基本上你需要獲得 API_TOKEN
,你接下來才能串接這整支 API,目的是為了讓你的資料與其他參賽者的資料有所區隔,所以我們需要聽過 API_TOKEN
來識別你的身份,以達到資料區隔的目的。
在此之前,你需要先申請你自己帳戶的 API_TOKEN
,首先請進入 The F2E 官方網站當中,如果已經註冊的就點選登入,如果尚未註冊的就請先申請帳號吧。
The F2E for 2019 - 官方網站 | 首頁
The F2E for 2019 - 官方網站 | 個人檔案
The F2E for 2019 - 官方網站 | 編輯個人檔案
Postman 官方網站
在開始使用之前,我會推薦大家使用 Postman
來作為你的 API 測試工具,至於他的使用教學你可以上網 Google。
Postman 官方網站 -> Postman | API Development Environment
在呼叫 API 的時候,只需要在 Headers
當中加入 Authorization
參數,並且將 TOKEN 帶入其中即可,帶入方式為 Bearer {your_token}
,舉例來說:
The F2E 網站上所獲得的 TOKEN 為 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
正確的 Value 帶入方式:Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
錯誤的 Value 帶入方式:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Postman 帶入 API_TOKEN
這種呼叫方式我會回傳你兩種格式,如果這個 API_TOKEN 格式是正確的、TOKEN 是存在的,那麼我會回傳你 JSON 資料,而另一種情況是可能格式不正確或者 TOKEN 並不存在,那麼我會回傳你整個網頁的登入表單。
伺服器回傳整個網頁的登入表單
那麼這時候問題就來了,為什麼錯誤的是回傳我整個網頁的登入表單,而不是用 JSON 來告訴我錯誤?原因是因為你呼叫時並沒有告訴我應該用什麼格式來回傳你,所以預設是將整個網頁登入表單作為回傳,如果你希望錯誤訊息也用 JSON 格式回傳的話,那麼你必須在 headers
當中再加入一個 accept
參數,這個參數的功能是明確的告訴伺服器你希望獲得指定格式的回傳,而這邊我們將帶入 application/json
用以表示我們希望伺服器回傳給我們的是 JSON 資料。
Postman 帶入 Accept
這時候再呼叫一次同樣的 API,就算發送錯誤格式,你也能正常獲得 JSON 格式的回傳資料。
有些參賽者在這邊可能會納悶,我要怎麼判斷例外錯誤?如果有錯誤的話,難道只會回傳 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 ;)
https://challenge.thef2e.com/api/thef2e2019/stage6/rooms
Inline Model:
{
"success" (boolean): 成功與否,
"item": [
(RoomItem) 房型資料,陣列
]
}
RoomItem:
{
"id" (string): 房間編號,
"imageUrl" (string): 圖片網址,
"normalDayPrice" (integer): 平日價格,
"holidayPrice" (integer): 假日價格,
"name" (string): 房間名稱
}
{
"success": true,
"item": [
{
"id": "KTLSls3bVUDZVk1Pt0R6tI2xeTzoznrqoWqdxjGzK7FuP1GCAbsHSu6MWdxO2rsU",
"imageUrl": "https://example.com/wtf.png",
"normalDayPrice": 1200,
"holidayPrice": 1199,
"name": "六角大飯店 - 珍珠拉麵套房"
}
]
}
none
https://challenge.thef2e.com/api/thef2e2019/stage6/room/{id}
{
"success" (boolean): 成功與否,
"room": [
{
"id" (string): 房間編號,
"imageUrl" (string): 圖片網址,
"normalDayPrice" (integer): 平日價格,
"holidayPrice" (integer): 假日價格,
"name" (string): 房間名稱,
"description" (string): 房間詳細說明
}
],
"booking": {
"name" (string): 訂房者名稱,
"tel" (string): 訂房者電話,
"date" (string): 訂房時間,
}
}
{
"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"
}
]
}
RoomItem(房型資料)
當中的 id(房間編號)
https://challenge.thef2e.com/api/thef2e2019/stage6/room/{id}
RoomItem(房型資料)
當中的 id(房間編號)
application/json
)Y-m-d
{
"success" (boolean): 成功與否,
"room": {
"id" (string): 房間編號,
"imageUrl" (string): 圖片網址,
"normalDayPrice" (integer): 平日價格,
"holidayPrice" (integer): 假日價格,
"name" (string): 房間名稱,
"description" (string): 房間詳細說明
},
"booking": {
"name" (string): 訂房者名稱,
"tel" (string): 訂房者電話,
"date" (string): 訂房時間,
}
}
{
"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"
}
]
}
https://challenge.thef2e.com/api/thef2e2019/stage6/rooms
{
"success" (boolean): 成功與否
}
{
"success": true
}
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",
]