1.1 REST[ful] API

Representational State Transfer (REST) is a software architectural style that defines a set of constraints to be used for creating web services. Web services that conform to the REST architectural style, termed RESTful web services, provide interoperability between computer systems on the Internet. RESTful web services allow the requesting systems to access and manipulate textual representations of web resources by using a uniform and predefined set of stateless operations.

stateless operation: The client–server communication is constrained by no client context being stored on the server between requests. Each request from any client contains all the information necessary to service the request, and session state is held in the client.

1.2 HTTPS (HTTP)

an extension of the Hypertext Transfer Protocol (HTTP). It is used for secure communication over a computer network, and is widely used on the Internet.

• HTTP:

  an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example by a mouse click or by tapping the screen. HTTP was developed to facilitate hypertext and the World Wide Web.

2.1 Request message

A typical request message that follows HTTP should have:

• a request line (e.g., GET /images/logo.png HTTP/1.1, which requests a resource called /images/logo.png from the server.)

  範例：

  資源路徑：/orgs/octokit/repos
  資源伺服器網址： https://api.github.com
  點https://api.github.com/orgs/octokit/repos可取得所要資源

資源伺服器網址也叫做root endpoint。

• request header fields (e.g., Accept-Language: en).

• an empty line

• an optional message body

2.2 Request methods

Current HTTP allows GET, PUT, POST, DELETE methods, etc. Among them,

• GET: 取得資源（資料）

• POST: 新增資源

2.3 Response message

• a status line which includes the status code and reason message (e.g., HTTP/1.1 200 OK, which indicates that the client’s request succeeded.)

• response header fields (e.g., Content-Type: text/html)

• an empty line

• an optional message body

3.1 Schema (綱要)

REST API的schema必需要細讀，GitHub描述到：

• All API access is over HTTPS, and accessed from https://api.github.com.

  資料伺服器: https://api.github.com

• All data is sent and received as JSON.

  Response message會是JSON格式。

• Three authentication ways: https://developer.github.com/v3/#authentication

  涉及個人資料的請求會需要認證，這裡有三種方法，認證資訊可放header也可放parameter。

• query parameters (查詢參數):

  提到兩種查詢參數方式，視Request Method而定：

  1. For GET requests, any parameters not specified as a segment in the path（指資源路徑） can be passed as an HTTP query string parameter——即在資源路徑的後面接著?key1=value1&key2+value2....等,key為要查詢參數名稱，value為查詢符合的條件值，注意要以問號開始。

     範例：https://api.github.com/repos/vmg/redcarpet/issues?state=closed

  2. For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’. 指以JSON格式來描述並放到Request message的message body裡。

3.2 典型HTTP Request說明

典型Request Message

• Host: 是伺服器網址，可想像成台北大學圖書館位置。

• Path: 是所要的書本在圖書館「內」的位置。

• Query String: 以?開頭，是在Path所在資源下的進一步搜尋條件，可想像Host/Path帶你到了台北大學圖書館的英文期刊經濟類書架，你在想書架上找出所有「產業經濟學」的期刊。

如果對照前面Request message的名詞：

• 第一行是Request line，說明了到了圖書館後要做的事（即Method和Query String等）地（即Path）。

• 接著的區塊都是Header fields。

• 接著以空行區隔。

• 接著是optional message body（即圖中的payload）。

5.1 範例1：Events

Github所有的動作都會形成一個event，如commit, push, pull request, create an issue等等。

這個範例在列出某個使用者產生的（公開）events。

List events performed by a user: https://developer.github.com/v3/activity/events/#list-events-performed-by-a-user

GET /users/:username/events

username<-"tpemartin"

"/users/:username/events" %>%
  str_replace("(:username)",username) %>%
  paste0("https://api.github.com",.) -> hostPath
hostPath

response <-GET(hostPath) # 完成請求
response # 查看

Response [https://api.github.com/users/tpemartin/events]
  Date: 2019-02-14 21:35
  Status: 200
  Content-Type: application/json; charset=utf-8
  Size: 135 kB

  {
    "id": "9032479754",
    "type": "WatchEvent",
    "actor": {
      "id": 6549594,
      "login": "tpemartin",
      "display_login": "tpemartin",
      "gravatar_id": "",
      "url": "https://api.github.com/users/...
...

response %>% content() -> responseContent # 查看內容

responseContent %>%
  map(~.x$type) %>%
  unlist %>%
  table

hostPath %>%
  paste0("?page=2")
response2 <-GET(hostPath) 
response2 %>% content() -> responseContent2 # 

5.2 範例2：Issues

這個範例在列出所有Assigned給某使用者的issues.

如果不清楚GitHub issue是什麼，可以點https://github.com/Jane0901/hackathon-practice/issues

Reference: https://developer.github.com/v3/issues/

GET /issues

"/issues" %>%
  paste0("https://api.github.com",.) -> hostPath
hostPath

hostPath %>% 
  paste0("?filter=assigned") -> hostPath

GET(hostPath)

5.3 範例3：Authentication

延續先前範例，但加上使用者授權。

之前有教授access token設定方式，那個方式每次打開RStudio都要再重執行一次，如果要一勞永逸，要以RProject方式來開啟RStudio（不清楚如何以RProject方式開啟，可跳過以下兩步驟）。

步驟1： 建立.Rprofile檔

file.edit(".Rprofile")

此檔內容請放此行，接著儲存關掉。

Sys.setenv(github_token="Your_token")

步驟2：重新以RProject方式開啟RStudio。

使用Query方式來授權，說明：https://developer.github.com/v3/#authentication

與先前唯一的不同是多了?access_token的hostPath延伸：

# HostPath
"/issues" %>%
  paste0("https://api.github.com",.) -> hostPath
hostPath
# Adding query
hostPath %>% 
  paste0("?filter=assigned&access_token=",Sys.getenv("github_token")) -> hostPath
GET(hostPath)-> responseOAuth
responseOAuth %>% content() -> responseOAuthList

5.4 範例4：issues

查詢指定repo內的issues

List issues for a repository

https://developer.github.com/v3/issues/#list-issues-for-a-repository

GET /repos/:owner/:repo/issues

# HostPath setup
"/repos/:owner/:repo/issues" %>%
  str_replace_all(
    c(
      "(:owner)"="Jane0901",
      "(:repo)"="hackathon-practice"
    )
  ) %>%
  paste0("https://api.github.com",.) -> hostPath
hostPath 
# Adding query
hostPath %>% 
  paste0("?access_token=",Sys.getenv("github_token")) -> hostPath
# Request
hostPath %>% 
  GET -> responseOAuth2
responseOAuth2 %>% content() -> responseOAuthList2

6.1 練習1：gitter chatroom

gitter.im chatroom

1. 到以下網頁使用你的gitter account註冊developer account：https://developer.gitter.im/docs/welcome
2. Sign in後點Apps會看到Personal Access Token，把它記下來，等一下看到$token的部份就換成它。

POST /v1/rooms/:roomId/chatMessages

$ curl -X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer $token" "https://api.gitter.im/v1/rooms/:roomId/chatMessages" -d '{"text":"You should also check https://irc.gitter.im/"}'

# 以下還缺:roomID故無法執行
hostPath<-"https://api.gitter.im/v1/rooms/:roomId/chatMessages"
POST(hostPath,
     add_headers(
       Authorization=paste0("Bearer ",Sys.getenv("gitter_token"))
     ),
     body=list(
       text="'來自03-REST-API.Rmd'程式所發出的練習"
     )) 

GET /v1/rooms

$ curl -i -H "Accept: application/json" -H "Authorization: Bearer $token" "https://api.gitter.im/v1/rooms"

hostPath <-
  "https://api.gitter.im/v1/rooms"
GET(hostPath,
    add_headers(
      Authorization=paste0("Bearer ",Sys.getenv("gitter_token"))
    )
    ) %>% content -> allMyRooms

allMyRooms %>%
  map(function(.x) str_detect(.x$name,"hackathon-practice")) %>%
  unlist %>% which %>%
  allMyRooms[[.]]

# 把:roomID補上
hostPath<-"https://api.gitter.im/v1/rooms/5c3f54eed73408ce4fb4f63d/chatMessages" 

POST(hostPath,
     add_headers(
       Authorization=paste0("Bearer ",Sys.getenv("gitter_token"))
     ),
     body=list(
       text="'來自03-REST-API.Rmd'程式所發出的練習，請勿理會"
     ),
     encode = "json") %>% content

6.2 練習2：氣象資料開放平台

這個練習在透過程式取得最新氣象資訊

1. 先註冊會員：https://pweb.cwb.gov.tw/CWBMEMBER2/registration.jsp

2. 依使用說明取得授權碼。

API 說明：http://opendata.cwb.gov.tw/dist/opendata-swagger.html

新北市樹林區未來2天天氣預報

在API說明找到新北市樹林區未來2天天氣預報，點它會有try it out；再點try it out會出現測試表單。填上你的$token，及各縣市所對應鄉鎮名稱填上樹林區，點表單下方的execute，會出現如下curl expression：

curl -X GET "https://opendata.cwb.gov.tw/api/v1/rest/datastore/F-D0047-069?Authorization=$token&locationName=%E6%A8%B9%E6%9E%97%E5%8D%80," -H "accept: application/json"

注意：authorization是以query形式進行。locationName是中文編碼結果。

hostPath <- "https://opendata.cwb.gov.tw/api/v1/rest/datastore/F-D0047-069"
# Add query
hostPath %>%
  paste0("?Authorization=",Sys.getenv("cwb_token"),"&locationName=%E6%A8%B9%E6%9E%97%E5%8D%80") -> hostPath

GET(hostPath) %>% content -> ntpuWeatherIn2Days

查詢結果：

ntpuWeatherIn2Days[["records"]][["locations"]][[1]][["location"]][[1]]$weatherElement

綜合練習1、2用程式在聊天室通知大家今天氣象：

ntpuWeatherIn2Days[["records"]][["locations"]][[1]][["location"]][[1]]$weatherElement %>% map(~.x$description)

todayWeather<-ntpuWeatherIn2Days[["records"]][["locations"]][[1]][["location"]][[1]]$weatherElement
todayWeather[[1]]$time[[1]]$elementValue[[1]]$value-> humidity
todayWeather[[4]]$time[[1]]$elementValue[[1]]$value-> temperature
todayWeather[[3]]$time[[1]]$elementValue[[1]]$value-> feelLike

textMessage<-"大家早，我是hackathon氣象播報機器人。目前溫度為攝氐_temperature_，體感溫度為攝氐_feelLike_，濕度為_humidity_%。想了解我是怎麼運作的，請學習03-REST-API.Rmd，並發揮你無限想像空限創造練習實例。 Cheers。"

textMessage %>%
  str_replace_all(
    c(
      "_temperature_"=temperature,
      "_feelLike_"=feelLike,
      "_humidity_"=humidity
    )
  ) -> textMessage
#textMessage

hostPath<-"https://api.gitter.im/v1/rooms/5c3f54eed73408ce4fb4f63d/chatMessages" 

POST(hostPath,
     add_headers(
       Authorization=paste0("Bearer ",Sys.getenv("gitter_token"))
     ),
     body=list(
       text=textMessage
     ),
     encode = "json") %>% content