* API Survey

1. API Survey #2
Firebase Realtime Database
@author Cara Wang <caraw@cnyes.com>
@since 2016/11/24
1

2. The Goal of API Survey
1. Analyze the design of public API ( compare to the principle of RESTful API)
Request path / Response format, etc…
2. Analyze the pros. and cros.
3. Playground (optional)
4. Feedback to our API design and implementation
2

3. What is RESTful API ?
1. 符合 REST 架構設計的 API
2. 符合: 六大目標所衍伸出來的五大特徵
3

4. Review: What is REST ?
1. http://whatisrest.com/
2. The 6 goals for implement RESTful API:
Simplicity
Scalability
Reliability
Performance
Modifiability
Visibility
4

5. Review: What is REST ?
1. Simplicity
如何讓架構的複雜度低
2. Scalability
如何在需求量暴增的情況下，也不影響服務結果
3. Reliability
如何在架構中部分損壞時，也不影響服務
4. Performance
如何不受網路傳輸限制，而影響回傳結果的時間
5

6. Review: What is REST ?
1. Modifiability
如何在對部分架構做更動時，也不影響服務
2. Visibility
如何讓傳輸過程中，可以看出所請求的服務是什麼，進而達到幫助完
成服務的目標
6

7. Review: What is REST ?
1. The 5 constraints (or characteristics):
Client-Server
7

8. 8

9. Review: What is REST ?
1. The 5 constraints (or characteristics):
Client-Server
Scalability: 依據不同 Request 可以做不同的擴充
例如: Elasticsearch 相關的服務需要擴充，新增 Elasticsearch Node
Modifiability: 更動單一個 API，不影響其他的
Layered System
9

10. 10

11. 11

12. 12

13. 13

14. 14

15. Review: What is REST ?
1. The 5 constraints (or characteristics):
Layered System
Scalability: 服務分層，依據需要的層級做擴充
Modifiability: 修改單一層級，不影響服務
Visibility: 要達到分層，需要讓傳輸過程的 Request / Response 是可以被解析的
Simplicity : 適當分工
15

16. Review: What is REST ?
1. The 5 constraints (or characteristics):
Interface / Uniform Contract
建立共通的合約
例如: Request 有 Lasutung 這個字時，表示他要打開 Lasutung 的視訊
Simplicity: 不需要對每個 Request 客製化
Modifiability: 知道合約的各方，可以獨立修改自己的部分而不影響其他合約方
Visibility: 在傳輸過程中，都可以透過合約來檢視這個 Request 的需求或是
Response 的大致含義
16

17. Review: What is REST ?
1. The 5 constraints (or characteristics):
Stateless
17

18. 18

19. 19

20. Review: What is REST ?
1. The 5 constraints (or characteristics):
Stateless
Scalability: 不用處理 Request 狀態被存在哪裡的問題
Modifiability: 不用擔心修改 Request 會對個別的使用者造成怎樣的影響
Visibility: Request 所需資訊會一次帶齊，中介者可以解析出該 Request 確切的請
求
Reliability: 部分 Server 服務中斷時，還是可以回應 Request
20

21. Review: What is REST ?
1. The 5 constraints (or characteristics):
Cache
Scalability: 不是所有流量都直接進到 Server
Performance: 經過的網路傳輸路徑短，回傳時間短
21

22. The Affection to API Design
Interface / Uniform Contract
1. HTTP Method
Method Verb Description
GET Read Read one or more specific resource(s)
POST Create Create one or more specific resource(s)
PUT / PATCH Update Update one or more specific resource(s)
DELETE Remove Remove one or more specific resource(s)
22

23. s
The Effection to the API Design
Interface / Uniform Contract
1. Resource Name
GET /users
GET /user /lasutung
POST /news
PUT /news/1
DELETE /users/lasutung/news/1 ??
DELETE /news/1 # Simplicity
DELETE /news/1,2,3
01.
02.
03.
04.
05.
06.
07.
23

24. The Effection to the API Design
Interface / Uniform Contract
1. HTTP Response
2xx: Success
3xx: Redirection
4xx: Client Errors
5xx: Service Errors
2. http://www.restapitutorial.com/httpstatuscodes.html
24

25. The Effection to the API Design
Interface / Uniform Contract
1. Response Payload
JSON
Error Message
Pagination
...
25

26. The Effection to the API Design
1. Idempotent: Can do it over and over again without causing different results
Method Idempotent
GET Yes
POST No
PUT Yes
PATCH No
DELETE Yes
https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
26

27. Firebase
Founded on Apr 6, 2011
27

28. Firebase Realtime Database API
HTTP Method
Method Firebase RESTful API
GET Reading Data Read
POST Pushing Data Create
PUT Writing Data Update
PATCH Updating Data Update
DELETE Removing Data Remove
28

29. Firebase Realtime Database API
1. Resource Name
https://{your-project-name}.firebaseio.com
/{your-firebase-model-lv-1}
/{your-firebase-model-lv-2}
...
.json
01.
02.
03.
04.
05.
29

30. 30

31. 31

32. 32

33. 33

34. 34

35. Firebase Realtime Database API
1. HTTP Status Code
Success: 200 OK
35

36. 36

37. Firebase Realtime Database API
1. HTTP Status Code
Success: 200 OK
Error:
37

38. 38

39. 39

40. 40

41. Firebase Realtime Database API
1. Response Payload
Success:
41

42. 42

43. 43

44. 44

45. 45

46. 46

47. Firebase Realtime Database API
1. Response Payload
Success:
Error:
47

48. 48

49. Pros and Cons
1. Pros
使用 HTTP Status Code 做溝通
一致用 200 代表成功，不會有其他 2xx 的可能
Payload 有 error 的 Key 時，HTTP Status Code 必定不是 2xx
49

50. 50

51. Pros and Cons
1. Pros
使用 HTTP Status Code 做溝通
Payload 有 error 的 Key 時，HTTP Status Code 必定不是 2xx
一致用 200 代表成功，不會有其他 2xx 的可能
2. Cons
Response Payload 沒有一致的格式，一旦後台 Key 值更動，則前台會直
接因為找不到 Key 而出錯
51

52. Demo
52

53. Q & A
53