10thMeetup-20190420-REST API Design Principles 되새기기

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

Copyright © 2019, Oracle and/or its affiliates. All rights reserved. |
Safe Harbor Statement
The following is intended to outline our general product direction. It is intended for
information purposes only, and may not be incorporated into any contract. It is not a
commitment to deliver any material, code, or functionality, and should not be relied upon
in making purchasing decisions. The development, release, timing, and pricing of any
features or functionality described for Oracle’s products may change and remains at the
sole discretion of Oracle Corporation.
Confidential – Oracle Internal/Restricted/Highly Restricted 2

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 자동화

오늘은…
1
코드 개발
후 코드 Push
개발자

오늘은…
코드 개발
후 코드 Push
개발자
요건 분석 디자인 & 프로토타입 개발
Backend
REST API 설계
Front-End
Back-End

SOAP
vs.
REST

Simple Object Access Protocol
vs.
REpresentational State Transfer

SOAP: Protocol
vs.
REST: Architectural Style

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)

– Uniform Interface
• Identification of Resources
• Manipulation of Resources through Representations
• Self-Descriptive Messages
• Hypermedia As The Engine Of Application State

Resource

#1. Use nouns to represent resources
: Resource를 명사로 표현하라.

첫 번째는 집합(Collection)

/users

두 번째는 단일 개체

/users/{userId}

#2. HTTP Operation를 사용하라

CREATE
READ
UPDATE
DELETE

POST
GET
PUT
DELETE

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

OCI IAM Service API > User 예시
Resource POST
(create)
GET
(read)
PUT
(update)
DELETE
(delete)
/users CreateUser ListUsers - -
/users/kildong - GetUser UpdateUser DeleteUser

추가로 필요한 조건들은 어떻게?

#3. 추가로 조건들은
Query Parameter를 사용하라

/users?title=Mr&status=active

/users?q={status=`active`}

#4. Error 메시지

Oracle OCI
HTTP Status Code: 401
{
"code": "NotAuthenticated",
"message": "The required information to complete authentication was not provided or was incorrect."
}
FaceBook
{
"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
{
"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…

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 – 사람을 위한 메시지
예시) OCI REST API
{
"code": "NotAuthenticated" or "34"
"message": "The required information to complete authentication was not provided or was incorrect."
}

#5. API 버전 관리

Version
• Facebook
– /v3.2/{user-id}/post
• Twitter
– /5/accounts
• Oracle PaaS: IDCS API
– /admin/v1/Users/{id}
• Oracle Cloud Infrastructure API
– /20160918/users/

그 밖에 사항

#6. 응답 메시지는 항상 모든 것을 줄까?

조회 칼럼 지정
• Facebook
– /{your-user-id}/photos
– /{your-user-id}/photos?fields=height,width
{
"data": [
{
"created_time": "2016-08-23T13:12:10+0000",
"id": "1308573619175349" // Photo ID
}
]
}
{
"data": [
{
"height": 720,
"width": 720,
"id": "1308573619175349" // Photo ID
}
]
}

#7. Page 처리는?

List Pagination
• FaceBook
– offset
– limit
• Twitter
– page
– rpp (return per page)

List Pagination
• FaceBook
– offset
– limit
• Twitter
– count
– cursor
• LinkedIn
– start
– count

List Pagination
• FaceBook
– offset
– limit
• Twitter
– count
– cursor
• LinkedIn
– start
– count
• Oracle PaaS API
– offset
– limit
• Oracle Cloud Infrastructure API
– page
– limit

Time-based Pagination
• FaceBook
– since
– until
– /me/posts?since=1364849754&until=1364587774
조회 결과의 개수가 최대 얼마나 클지를
실행 전까지는 알 수 없습니다.
질문. 직접 개발한다면, 결과를 어떤 방식으로 줄까요?

HATEOAS
(Hypermedia
As The Engine Of Application State)

Hypermedia As The Engine Of Application State
• FaceBook
– /me/posts?offset=0&limit=2
{
"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&~~~~"
}
}

Hypermedia As The Engine Of Application State
• FaceBook
– /me/posts?since=1298937600&until=1546300800&limit=2
{
"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=~~~~"
}
}

Store
Or Association?

/users/{userId}/state

Non Resource

HelloWorld
Translate
Exchange

Use verb
: 동사로 표현하라.

/translate?from=korean&to=english

• KakaoPay API

REST API Design Principles

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

10thMeetup-20190420-REST API Design Principles 되새기기

10thMeetup-20190420-REST API Design Principles 되새기기

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à 10thMeetup-20190420-REST API Design Principles 되새기기

Similaire à 10thMeetup-20190420-REST API Design Principles 되새기기 (20)

Dernier

Dernier (20)

10thMeetup-20190420-REST API Design Principles 되새기기