The document discusses REST API design principles, including: 1. Resources should be represented as nouns and HTTP operations like GET, POST, PUT, DELETE should be used to manipulate resources. 2. Additional conditions can be specified using query parameters. 3. Both HTTP status codes and custom error codes should be used to indicate errors, with codes providing context and messages for humans. 4. API versions should be included in the URI to manage changes over time. 5. Pagination, filtering of response fields, and hypermedia as the engine of application state (HATEOAS) should be supported to navigate between resource representations.

2. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted
10th Oracle
Developer
MeetupREST API Design Principles
되새기기
이동희(DongHee Lee)
Principal Solution Engineer
Oracle Korea Solution Engineering

3. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 3
Microservice 배포
지난 3월 16일….
1
코드 개발
후 코드 Push
2
Wercker
빌드 후 Image 생성
3
Image를
Registry에 Push
4
Kubernetes에
배포
5
Image를 가져와서
Kubernetes 내 Container 기동
개발자
OCI
Registry
OCI
Container Engine
for Kubernetes
(OKE)
Wercker 서비스를 이용한 Workflow 자동화

4. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 4
오늘은…
1
코드 개발
후 코드 Push
개발자

5. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 5
오늘은…
코드 개발
후 코드 Push
개발자
요건 분석 디자인 & 프로토타입 개발
Backend
REST API 설계
Front-End
Back-End

6. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 6
SOAP
vs.
REST

7. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 7
Simple Object Access Protocol
vs.
REpresentational State Transfer

8. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 8
SOAP: Protocol
vs.
REST: Architectural Style

9. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
What is REST?
• 2000년, Roy Fielding의 박사 논문에서 제시된 분산 Hypermedia 시스템을 위한 아키텍처 스타일
• Guiding Principles of REST
– Client–Server
– Stateless
– Cacheable
– Uniform interface
• identification of resources
• manipulation of resources through representations
• self-descriptive messages
• hypermedia as the engine of application state
– Layered system
– Code on demand (optional)
Confidential – Oracle Internal/Restricted/Highly Restricted 9

10. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 10
– Uniform Interface
• Identification of Resources
• Manipulation of Resources through Representations
• Self-Descriptive Messages
• Hypermedia As The Engine Of Application State

11. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 11
Resource

12. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 12
#1. Use nouns to represent resources
: Resource를 명사로 표현하라.

13. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 13
첫 번째는 집합(Collection)

14. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 14
/users

15. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 15
두 번째는 단일 개체

16. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 16
/users/{userId}

17. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 17
#2. HTTP Operation를 사용하라

18. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 18
CREATE
READ
UPDATE
DELETE

19. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 19
POST
GET
PUT
DELETE

20. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 20
Resource POST
(create)
GET
(read)
PUT
(update)
DELETE
(delete)
/users
Create
new user
List users
Bulk Update
users
Delete
all users
/users/kildong - Get kildong Update kildong Delete kildong

21. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 21
OCI IAM Service API > User 예시
Resource POST
(create)
GET
(read)
PUT
(update)
DELETE
(delete)
/users CreateUser ListUsers - -
/users/kildong - GetUser UpdateUser DeleteUser

22. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 22
추가로 필요한 조건들은 어떻게?

23. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 23
#3. 추가로 조건들은
Query Parameter를 사용하라

24. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 24
/users?title=Mr&status=active

25. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 25
/users?q={status=`active`}

26. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 26
#4. Error 메시지

27. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 27
Oracle OCI
HTTP Status Code: 401
{
"code": "NotAuthenticated",
"message": "The required information to complete authentication was not provided or was incorrect."
}
FaceBook
HTTP Status Code: 200
{
"error": {
"message": "Message describing the error",
"type": "OAuthException",
"code": 190,
"error_subcode": 460,
"error_user_title": "A title",
"error_user_msg": "A message",
"fbtrace_id": "EJplcsCHuLu“
}
}
HTTP Status Code는 항상 200, 오류 코드와 하위 오류코드 사용
Twitter
HTTP Status Code: 404
{
"errors": [ {
"message":"Sorry, that page does not exist",
"code":34
}]
}
HTTP Status Code중 15개 사용, 오류 코드 사용
코드 이름 조치
190 액세스 토큰이 만료됨 새 액세스 토큰을 가져옵니다.
코드 이름 설명
34 Sorry, that page does not exist
Corresponds with HTTP 404. The
specified resource was not found.
HTTP Status Code Error Code Description
401 NotAuthenticated
The required authentication information was
not provided or was incorrect…

28. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
2가지 Code 사용
• HTTP Status Codes - 클라이언트 코드를 위해 사용
– 1xx (Informational): The request was received, continuing process
– 2xx (Successful): The request was successfully received, understood, and accepted
– 3xx (Redirection): Further action needs to be taken in order to complete the request
– 4xx (Client Error): The request contains bad syntax or cannot be fulfilled
– 5xx (Server Error): The server failed to fulfill an apparently valid request
• Custom Error Codes – 사람을 위한 메시지
Confidential – Oracle Internal/Restricted/Highly Restricted 28
예시) OCI REST API
{
"code": "NotAuthenticated" or "34"
"message": "The required information to complete authentication was not provided or was incorrect."
}

29. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 29
#5. API 버전 관리

30. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
Version
• Facebook
– /v3.2/{user-id}/post
• Twitter
– /5/accounts
• Oracle PaaS: IDCS API
– /admin/v1/Users/{id}
• Oracle Cloud Infrastructure API
– /20160918/users/
Confidential – Oracle Internal/Restricted/Highly Restricted 30

31. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 31
그 밖에 사항

32. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 32
#6. 응답 메시지는 항상 모든 것을 줄까?

33. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
조회 칼럼 지정
• Facebook
– /{your-user-id}/photos
– /{your-user-id}/photos?fields=height,width
Confidential – Oracle Internal/Restricted/Highly Restricted 33
{
"data": [
{
"created_time": "2016-08-23T13:12:10+0000",
"id": "1308573619175349" // Photo ID
}
]
}
{
"data": [
{
"height": 720,
"width": 720,
"id": "1308573619175349" // Photo ID
}
]
}

34. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 34
#7. Page 처리는?

35. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
List Pagination
• FaceBook
– offset
– limit
• Twitter
– page
– rpp (return per page)
Confidential – Oracle Internal/Restricted/Highly Restricted 35

36. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
List Pagination
• FaceBook
– offset
– limit
• Twitter
– count
– cursor
• LinkedIn
– start
– count
Confidential – Oracle Internal/Restricted/Highly Restricted 36

37. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
List Pagination
• FaceBook
– offset
– limit
• Twitter
– count
– cursor
• LinkedIn
– start
– count
Confidential – Oracle Internal/Restricted/Highly Restricted 37
• Oracle PaaS API
– offset
– limit
• Oracle Cloud Infrastructure API
– page
– limit

38. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
Time-based Pagination
• FaceBook
– since
– until
– /me/posts?since=1364849754&until=1364587774
Confidential – Oracle Internal/Restricted/Highly Restricted 38
조회 결과의 개수가 최대 얼마나 클지를
실행 전까지는 알 수 없습니다.
질문. 직접 개발한다면, 결과를 어떤 방식으로 줄까요?

39. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 39
HATEOAS
(Hypermedia
As The Engine Of Application State)

40. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
Hypermedia As The Engine Of Application State
• FaceBook
– /me/posts?offset=0&limit=2
Confidential – Oracle Internal/Restricted/Highly Restricted 40
{
"data": [
{
"message": "",
"created_time": "2012-03-20T06:04:36+0000",
"id": ""
},
{
"message": "",
"created_time": "2012-01-19T11:26:04+0000",
"id": "2700528826685328_256082517796650"
}
],
"paging": {
"previous": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&~~~&__previous=1",
"next": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&~~~~"
}
}

41. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
Hypermedia As The Engine Of Application State
• FaceBook
– /me/posts?since=1298937600&until=1546300800&limit=2
Confidential – Oracle Internal/Restricted/Highly Restricted 41
{
"data": [
{
"message": "",
"created_time": "2012-03-20T06:04:36+0000",
"id": "2700528826685328_295284543876447"
},
{
"message": "",
"created_time": "2012-01-19T11:26:04+0000",
"id": "2700528826685328_256082517796650"
}
],
"paging": {
"previous": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&since=1332223476
&format=json&access_token=~~~~&__paging_token=~~~~&__previous=1",
"next": "https://graph.facebook.com/v3.2/2700528826685328/posts?limit=2&since=1298937600
&format=json&access_token=~~~~&until=1326972364&__paging_token=~~~~"
}
}

42. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 42
Store
Or Association?

43. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 43
/users/{userId}/state

44. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 44
Non Resource

45. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 45
HelloWorld
Translate
Exchange

46. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 46
Use verb
: 동사로 표현하라.

47. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 47
/translate?from=korean&to=english

48. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
• KakaoPay API
Confidential – Oracle Internal/Restricted/Highly Restricted 48

49. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
• KakaoPay API
Confidential – Oracle Internal/Restricted/Highly Restricted 49

50. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 50
REST API Design Principles

51. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
REST API Design Principles
• #1. Resource를 명사로 표현하라
– 첫 번째는 집합(Collection), 두 번째는 단일개체
• #2. HTTP Operation를 사용하라
• #3. 추가로 조건들은 Query Parameter를 사용하라
• #4. Error 메시지는 HTTP Response Codes & Custom Error Codes
• #5. API 버전 관리 – /v1/users or /20160918/users
Confidential – Oracle Internal/Restricted/Highly Restricted 51

52. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 52
## 다음 세션을 준비사항 ##
- GitHub 계정
- 개인 노트북에 node.js 설치

53. Copyright © 2019, Oracle and/or its affiliates. All rights reserved. | Confidential – Oracle Internal/Restricted/Highly Restricted 53