SlideShare a Scribd company logo
1 of 19
Download to read offline
RESTful API
Design Guide
김 병 부 (Benjamin Kim)
byungboor@naver.com
http://myboor.tistory.com
Introspection
• Resource의 나열 – RESTful의 본질 외면
– CRUD 제외한 operation 에 대한 어려움
– 수많은 Resource
• 보안상 문제점
– Key exchange
– 메시지 암호화 X
– Error 메시지의 난립
– HTTP Resource에 노출된 정보들
• 통일된 Guide 없이 임기 응변
• OpenAPI가 될 수 없다.
Table of Contents
• RESTful API fundamental concept
• Use RESTful URLs and actions
• Error Handling
• Security
• HATEOAS (optional)
• Reference Link
RESTful API fundamental concept
• Resource
– HTTP URL format
• Method
– HTTP Standard Methods for CRUD
operations
– POST - Create
– GET - Read
– DELETE - Delete
– PUT - Update
• Message
– XML, YAML, JSON and HTML format
HTTP POST, /instances
{
“instance” : {
“name” : “xmyboor001”,
“specId” : “x1.large”
}
}
Use RESTful URLs and actions #1
• 명사를 사용한다.
• 복수형을 사용한다.
• 구체적인 이름을 사용한다.
– (O) HTTP GET /instances
– (O) HTTP GET /instances/1024
– (O) HTTP GET /instances/sdcconsoledb01
– (X) HTTP GET /instance
– (X) HTTP GET /instances?id=1024
– (X) HTTP GET /getInstance
• 예외상황
– CRUD를 제외한 다른 명령어는 어떻게?
– E.g. Chef의 Role을 실행하는 경우
(O) HTTP POST /role/2048/run
(X) HTTP GET
/role/run?instanceId=1024&roleId=2048
Use RESTful URLs and actions #2
• 리소스간 관계는 sub-resource를 사용한
다.
– HTTP GET /instances/1024/volumes/204
– HTTP POST / instances/1024/volumes
• Paging은 limit, offset 키워드를 사용한
다.
– Facebook Style
– HTTP GET /instances?offset=100&limit=30
• Partial Response (Optional)
– Facebook Style
– HTTP GET /instances?field=instanceId,name
• ER Diagram
– Table Instance and Volume
Use RESTful URLs and actions #3
Resource GET
Read
POST
Create
PUT
Update
DELETE
/instances Returns a list of
instances
Create a new
Instance
Bulk update of
instances
Delete all instances
/instances/1024 Returns a specific
instance
Method not
allowed (405 error)
Updates a specific
instance
Delete a specific
instance
/instances/1024/vol
umes
Returns a list of
volumes of the
instance
Create a new
volume at the
instance
Bulk update of
volumes at the
instance
Delete all volumes
at the instance
/instances/1024/vol
umes/204
Return a specific
volume of the
instance
Method not
allowed (405 error)
Update a specific
volume at the
instance
Delete a specific
volume at the
instance
Use RESTful URLs and actions #4
• Searching
– 파라미터 이름 ‘q’를 이용한다.
– q=name=myboor004,zone=qa&limit=30
– URLEncode 를 사용한다.
– HTTP GET /instences?q=name%3Dmyboor004,zone%3D=qa&limit=30
• Sorting
– 파라미터 이름 ‘sort’ 를 이용한다.
– 기호 ‘-’ descending
– 기호 ‘+’ ascending
– HTTP GET /instences?sort=-instanceId,+
Use RESTful URLs and actions #5
• Version
– Mandatory
– REST Resource에 정의하는 방법, HTTP Header에 정의 하는 방법 등이 있음
– Resource 에 정의 한다.
– HTTP GET /sdc/api/v1.0/instances
• HTTP headers for serialization formats
– Client, Server 모두 format을 지정해야 한다.
– Format은 HTTP-Header의 context-type 을 사용한다.
– 기본적으로 JSON format을 사용한다.
MessageType Content-Type
JSON application/json
Use RESTful URLs and actions #6
• eXtended headers for REST API
– 다음과 같은 customized 된 추가 헤더를 사용한다.
– Mandatory or 401 error
– Client Side
Header Name Description
X-NETMARBLE-LOGINID 로그인 아이디 정보
X-NETMARBLE-CHANNEL OpenAPI에 접속하는 Channel 정보
Error Handling #1
• Error 처리는 HTTP Status Code를 사용한다.
• 약 70여 개의 HTTP Status Code가 존재
– http://en.wikipedia.org/wiki/Http_error_codes
• 다음과 같은 방식으로 HTTP Status Code를 사용한다.
– 200 - OK : 성공 (동기식)
– 201 - OK : 성공 (비동기식)
– 400 - Bad Request : Parameter validation 실패, Json 포멧 에러
– 401 - Unauthorized : 인증 실패
– 403 – Forbidden : 인가 실패
– 404 - Not Found
– 410 - Gone : 요청된 resource가 더 이상 존재하지 않을때 발생하는 에러.
– 500 - Internal Server Error : 서버 측 에러
Error Handling #2
• Error Payload
– HTTP Status code 만으로 충분한 메시지가 전달되기 힘들다.
– 서버에서는 다음과 같은 format으로 response body에 응답한다.
HTTP Status Code : 401
{
“status” : “401”,
“userMessage” : “Authentication Failure”,
“errorCode” : “30201”,
“errorInfo” : “http://sdn/wiki/errors/30201”
}
– 단 2XX code에서는 payload가 필요없다.
– Exception Stack 정보를 포함하지 않는다.
Security #1
• 인증 (Authentication)
– REST API를 호출하는 대상을 확인하는 절차
• 인가 (Authorization)
– REST API의 resource를 사용할 권한이 있는지 확인하는 절차
• 네트워크 레벨의 암호화
– 네트워크 프로토콜 단의 암호화.
– HTTPS 를 사용한다.
• 메시지 무결성 보장
– 메시지 변조를 방지하기 위해서, 메시지의 Hash Code를 비교하여 메시지 무결성을 확인
• 메시지 본문 암호화
– 네트워크 레벨의 암호화를 사용 못하는 경우, 메시지 본문을 암호화한다.
Security #2
• Authentication
– Basic Authentication 은 가능한 피한다. 계정와 암호를 Base64 인코딩하므로 디코딩 가능함.
– Token 방식의 digest algorithm – HMAC-SHA256
– Use OAuth 1.0a or Oauth 2
• API Key를 사용
– Entropy
– Reduced Exposure
– Traceability
– Avoid Sessions
– Authenticate every request
Security #3
• API Access Token 인증방법
– Use HTTPS
– Token exchange using Secure Cookie
https://www.owasp.org/index.php/SecureFlag
– Access token is valid within expireTime
– 조대협님 블로그 (http://bcho.tistory.com/955)
Security #4
• REST API Message Policy in Spring MVC
– Controller, Service, Dao
– ValueObject – Table Record와 일치
> ValueObject 를 JSON 포멧으로 마샬링할 때,
중요한 데이터까지 사용자에게 노출된다.
– DomainObject for JSON Message
– Controller Layer에서 marshalling, unmarshalling 하기 위해서 Domain 객체를 사용한다.
HATEOAS (optional)
• HATEOAS
– Hypermedia as the engine of application state
– HTTP Response에 다음 action에 관한 링크를 제공
– E.g. detail 링크를 제공하는 경우
– E.g. paging 링크를 제공하는 경우
HTTP GET /instances?limit=30&offset=30
{
“rows” : [
{“instanceId” : 1024, “name” : “sdcconsoledb01”},
{“instanceId” : 1025, “name” : “sdcconsoledb02”}
],
“links” : [
{“rel” : “prev”, “href” : “http://sdc/instances?limit=30&offset=0”},
{“rel” : “next”, “href” : “http://sdc/instances?limit=30&offset=60”}
]
}
Reference Link
• http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/
• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• http://restful-api-design.readthedocs.org/en/latest/resources.html
• http://www.slideshare.net/stormpath/secure-your-rest-api-the-right-way
• http://bcho.tistory.com/914
• http://bcho.tistory.com/953
• http://bcho.tistory.com/955
Restful API guide

More Related Content

What's hot

Ksug 세미나 (윤성준) (20121208)
Ksug 세미나 (윤성준) (20121208)Ksug 세미나 (윤성준) (20121208)
Ksug 세미나 (윤성준) (20121208)Sungjoon Yoon
 
[Hello world 오픈세미나]open api client개발
[Hello world 오픈세미나]open api client개발[Hello world 오픈세미나]open api client개발
[Hello world 오픈세미나]open api client개발NAVER D2
 
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기Manjong Han
 
Spring 4.x Web Application 살펴보기
Spring 4.x Web Application  살펴보기Spring 4.x Web Application  살펴보기
Spring 4.x Web Application 살펴보기Ji Heon Kim
 
Naver 오픈api-마이그레이션가이드 20160913-리뷰
Naver 오픈api-마이그레이션가이드 20160913-리뷰Naver 오픈api-마이그레이션가이드 20160913-리뷰
Naver 오픈api-마이그레이션가이드 20160913-리뷰NAVER D2
 
Resource Handling in Spring MVC
Resource Handling in Spring MVCResource Handling in Spring MVC
Resource Handling in Spring MVCArawn Park
 
[D2 CAMPUS]웹 개발자의 스펙 : HTTP
[D2 CAMPUS]웹 개발자의 스펙 : HTTP[D2 CAMPUS]웹 개발자의 스펙 : HTTP
[D2 CAMPUS]웹 개발자의 스펙 : HTTPNAVER D2
 
F3 네이버오픈api만드는매쉬업
F3 네이버오픈api만드는매쉬업F3 네이버오픈api만드는매쉬업
F3 네이버오픈api만드는매쉬업NAVER D2
 
[오픈소스컨설팅]Spring MVC
[오픈소스컨설팅]Spring MVC [오픈소스컨설팅]Spring MVC
[오픈소스컨설팅]Spring MVC Ji-Woong Choi
 
E-Gov 기반 Mobile Web Friendly 개발
E-Gov 기반 Mobile Web Friendly 개발E-Gov 기반 Mobile Web Friendly 개발
E-Gov 기반 Mobile Web Friendly 개발JavaCommunity.Org
 
[D2SF] Naver 오픈 API 가이드
[D2SF] Naver 오픈 API 가이드[D2SF] Naver 오픈 API 가이드
[D2SF] Naver 오픈 API 가이드NAVER D2 STARTUP FACTORY
 
진짜기초 Node.js
진짜기초 Node.js진짜기초 Node.js
진짜기초 Node.jsWoo Jin Kim
 
서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)수보 김
 
Spring-Boot (springcamp2014)
Spring-Boot (springcamp2014)Spring-Boot (springcamp2014)
Spring-Boot (springcamp2014)sung yong jung
 
Mean 스택을 사용한 IoT 개발
Mean 스택을 사용한 IoT 개발Mean 스택을 사용한 IoT 개발
Mean 스택을 사용한 IoT 개발Jay Park
 

What's hot (20)

Ksug 세미나 (윤성준) (20121208)
Ksug 세미나 (윤성준) (20121208)Ksug 세미나 (윤성준) (20121208)
Ksug 세미나 (윤성준) (20121208)
 
[Hello world 오픈세미나]open api client개발
[Hello world 오픈세미나]open api client개발[Hello world 오픈세미나]open api client개발
[Hello world 오픈세미나]open api client개발
 
RESTful Java
RESTful JavaRESTful Java
RESTful Java
 
RESTful API
RESTful APIRESTful API
RESTful API
 
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기
Flask, Redis, Retrofit을 이용한 Android 로그인 서비스 구현하기
 
Spring 4.x Web Application 살펴보기
Spring 4.x Web Application  살펴보기Spring 4.x Web Application  살펴보기
Spring 4.x Web Application 살펴보기
 
Node.js 기본
Node.js 기본Node.js 기본
Node.js 기본
 
Naver 오픈api-마이그레이션가이드 20160913-리뷰
Naver 오픈api-마이그레이션가이드 20160913-리뷰Naver 오픈api-마이그레이션가이드 20160913-리뷰
Naver 오픈api-마이그레이션가이드 20160913-리뷰
 
Resource Handling in Spring MVC
Resource Handling in Spring MVCResource Handling in Spring MVC
Resource Handling in Spring MVC
 
Node.js 기본과정
Node.js 기본과정Node.js 기본과정
Node.js 기본과정
 
[D2 CAMPUS]웹 개발자의 스펙 : HTTP
[D2 CAMPUS]웹 개발자의 스펙 : HTTP[D2 CAMPUS]웹 개발자의 스펙 : HTTP
[D2 CAMPUS]웹 개발자의 스펙 : HTTP
 
F3 네이버오픈api만드는매쉬업
F3 네이버오픈api만드는매쉬업F3 네이버오픈api만드는매쉬업
F3 네이버오픈api만드는매쉬업
 
[오픈소스컨설팅]Spring MVC
[오픈소스컨설팅]Spring MVC [오픈소스컨설팅]Spring MVC
[오픈소스컨설팅]Spring MVC
 
Node.js 심화과정
Node.js 심화과정Node.js 심화과정
Node.js 심화과정
 
E-Gov 기반 Mobile Web Friendly 개발
E-Gov 기반 Mobile Web Friendly 개발E-Gov 기반 Mobile Web Friendly 개발
E-Gov 기반 Mobile Web Friendly 개발
 
[D2SF] Naver 오픈 API 가이드
[D2SF] Naver 오픈 API 가이드[D2SF] Naver 오픈 API 가이드
[D2SF] Naver 오픈 API 가이드
 
진짜기초 Node.js
진짜기초 Node.js진짜기초 Node.js
진짜기초 Node.js
 
서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)
 
Spring-Boot (springcamp2014)
Spring-Boot (springcamp2014)Spring-Boot (springcamp2014)
Spring-Boot (springcamp2014)
 
Mean 스택을 사용한 IoT 개발
Mean 스택을 사용한 IoT 개발Mean 스택을 사용한 IoT 개발
Mean 스택을 사용한 IoT 개발
 

Viewers also liked

RESTful API 제대로 만들기
RESTful API 제대로 만들기RESTful API 제대로 만들기
RESTful API 제대로 만들기Juwon Kim
 
RESTful pattern policy
RESTful pattern policyRESTful pattern policy
RESTful pattern policyNamhoon Kim
 
20140820 멀티플랫폼 인증서버_개발
20140820 멀티플랫폼 인증서버_개발20140820 멀티플랫폼 인증서버_개발
20140820 멀티플랫폼 인증서버_개발준상 신
 
Understanding open api service 엄준일
Understanding open api service 엄준일Understanding open api service 엄준일
Understanding open api service 엄준일준일 엄
 
Daum 검색/지도 API (이정주)
Daum 검색/지도 API (이정주)Daum 검색/지도 API (이정주)
Daum 검색/지도 API (이정주)Daum DNA
 
Understanding Open Api Service
Understanding Open Api ServiceUnderstanding Open Api Service
Understanding Open Api Service준일 엄
 
[NEXT] Flask 로 Restful API 서버 만들기
[NEXT] Flask 로 Restful API 서버 만들기 [NEXT] Flask 로 Restful API 서버 만들기
[NEXT] Flask 로 Restful API 서버 만들기 YoungSu Son
 
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교Lee Ji Eun
 
모바일 개발 트랜드
모바일 개발 트랜드모바일 개발 트랜드
모바일 개발 트랜드Terry Cho
 
SOAP 기반/ RESTful기반 웹서비스 비교
SOAP 기반/ RESTful기반 웹서비스 비교SOAP 기반/ RESTful기반 웹서비스 비교
SOAP 기반/ RESTful기반 웹서비스 비교seungdols
 
기획자를 위한 OAuth
기획자를 위한 OAuth기획자를 위한 OAuth
기획자를 위한 OAuthMinwoo Park
 
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)Jeongho Shin
 
OAuth2 - API 인증을 위한 만능도구상자
OAuth2 - API 인증을 위한 만능도구상자OAuth2 - API 인증을 위한 만능도구상자
OAuth2 - API 인증을 위한 만능도구상자Minwoo Park
 
SOAP REST 이해
SOAP REST 이해SOAP REST 이해
SOAP REST 이해Jake Yoon
 
알고리즘과 자료구조
알고리즘과 자료구조알고리즘과 자료구조
알고리즘과 자료구조영기 김
 
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬2013 빅데이터 및 API 기술 현황과 전망- 윤석찬
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬Channy Yun
 
[124] 하이브리드 앱 개발기 김한솔
[124] 하이브리드 앱 개발기 김한솔[124] 하이브리드 앱 개발기 김한솔
[124] 하이브리드 앱 개발기 김한솔NAVER D2
 
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다Dae Kim
 
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민NAVER D2
 
Naver Open Api Reference Manual
Naver Open Api Reference ManualNaver Open Api Reference Manual
Naver Open Api Reference Manual성웅 강
 

Viewers also liked (20)

RESTful API 제대로 만들기
RESTful API 제대로 만들기RESTful API 제대로 만들기
RESTful API 제대로 만들기
 
RESTful pattern policy
RESTful pattern policyRESTful pattern policy
RESTful pattern policy
 
20140820 멀티플랫폼 인증서버_개발
20140820 멀티플랫폼 인증서버_개발20140820 멀티플랫폼 인증서버_개발
20140820 멀티플랫폼 인증서버_개발
 
Understanding open api service 엄준일
Understanding open api service 엄준일Understanding open api service 엄준일
Understanding open api service 엄준일
 
Daum 검색/지도 API (이정주)
Daum 검색/지도 API (이정주)Daum 검색/지도 API (이정주)
Daum 검색/지도 API (이정주)
 
Understanding Open Api Service
Understanding Open Api ServiceUnderstanding Open Api Service
Understanding Open Api Service
 
[NEXT] Flask 로 Restful API 서버 만들기
[NEXT] Flask 로 Restful API 서버 만들기 [NEXT] Flask 로 Restful API 서버 만들기
[NEXT] Flask 로 Restful API 서버 만들기
 
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교
FIDO기반 생체인식 인증기술_SK플래닛@tech세미나판교
 
모바일 개발 트랜드
모바일 개발 트랜드모바일 개발 트랜드
모바일 개발 트랜드
 
SOAP 기반/ RESTful기반 웹서비스 비교
SOAP 기반/ RESTful기반 웹서비스 비교SOAP 기반/ RESTful기반 웹서비스 비교
SOAP 기반/ RESTful기반 웹서비스 비교
 
기획자를 위한 OAuth
기획자를 위한 OAuth기획자를 위한 OAuth
기획자를 위한 OAuth
 
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)
더 나은 S/W를 만드는 것에 관하여 (OKKY 세미나)
 
OAuth2 - API 인증을 위한 만능도구상자
OAuth2 - API 인증을 위한 만능도구상자OAuth2 - API 인증을 위한 만능도구상자
OAuth2 - API 인증을 위한 만능도구상자
 
SOAP REST 이해
SOAP REST 이해SOAP REST 이해
SOAP REST 이해
 
알고리즘과 자료구조
알고리즘과 자료구조알고리즘과 자료구조
알고리즘과 자료구조
 
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬2013 빅데이터 및 API 기술 현황과 전망- 윤석찬
2013 빅데이터 및 API 기술 현황과 전망- 윤석찬
 
[124] 하이브리드 앱 개발기 김한솔
[124] 하이브리드 앱 개발기 김한솔[124] 하이브리드 앱 개발기 김한솔
[124] 하이브리드 앱 개발기 김한솔
 
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다
클라우드 기반 Unity 게임 서버 구축, 60분이면 충분하다
 
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민
[125]react로개발자2명이플랫폼4개를서비스하는이야기 심상민
 
Naver Open Api Reference Manual
Naver Open Api Reference ManualNaver Open Api Reference Manual
Naver Open Api Reference Manual
 

Similar to Restful API guide

웹 크롤링 (Web scraping) 의 이해
웹 크롤링 (Web scraping) 의 이해웹 크롤링 (Web scraping) 의 이해
웹 크롤링 (Web scraping) 의 이해2minchul
 
WoO 2012-Web 서비스 기술
WoO 2012-Web 서비스 기술WoO 2012-Web 서비스 기술
WoO 2012-Web 서비스 기술Changhwan Yi
 
Elastic Search (엘라스틱서치) 입문
Elastic Search (엘라스틱서치) 입문Elastic Search (엘라스틱서치) 입문
Elastic Search (엘라스틱서치) 입문SeungHyun Eom
 
대용량 분산 아키텍쳐 설계 #5. rest
대용량 분산 아키텍쳐 설계 #5. rest대용량 분산 아키텍쳐 설계 #5. rest
대용량 분산 아키텍쳐 설계 #5. restTerry Cho
 
Web App Security 2015.10
Web App Security 2015.10Web App Security 2015.10
Web App Security 2015.10Chanjin Park
 
Http 완벽 가이드(2장 url과 리소스)
Http 완벽 가이드(2장 url과 리소스)Http 완벽 가이드(2장 url과 리소스)
Http 완벽 가이드(2장 url과 리소스)Choonghyun Yang
 
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요dgmit2009
 
03. HTTPS & Restful
03. HTTPS & Restful03. HTTPS & Restful
03. HTTPS & RestfulShin Kim
 
HTTP 발표자료 - 김연수
HTTP 발표자료 - 김연수HTTP 발표자료 - 김연수
HTTP 발표자료 - 김연수Yeon Soo Kim
 
IT 일반기술 강의자료_ed10
IT 일반기술 강의자료_ed10IT 일반기술 강의자료_ed10
IT 일반기술 강의자료_ed10hungrok
 
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취NAVER D2
 
Http 헤더
Http 헤더Http 헤더
Http 헤더kidoki
 
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)SangHoon Han
 
REST with Spring
REST with SpringREST with Spring
REST with Spring강우 김
 
Http 완벽가이드(3장 http 메시지)
Http 완벽가이드(3장 http 메시지)Http 완벽가이드(3장 http 메시지)
Http 완벽가이드(3장 http 메시지)Choonghyun Yang
 
[APL OJT] REST API TEST
[APL OJT] REST API TEST[APL OJT] REST API TEST
[APL OJT] REST API TESTJae-yeol Lee
 
2Naver Open Android API Translation At DCamp
2Naver Open Android API Translation At DCamp2Naver Open Android API Translation At DCamp
2Naver Open Android API Translation At DCampJeikei Park
 
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)진태 이
 

Similar to Restful API guide (20)

웹 크롤링 (Web scraping) 의 이해
웹 크롤링 (Web scraping) 의 이해웹 크롤링 (Web scraping) 의 이해
웹 크롤링 (Web scraping) 의 이해
 
WoO 2012-Web 서비스 기술
WoO 2012-Web 서비스 기술WoO 2012-Web 서비스 기술
WoO 2012-Web 서비스 기술
 
Elastic Search (엘라스틱서치) 입문
Elastic Search (엘라스틱서치) 입문Elastic Search (엘라스틱서치) 입문
Elastic Search (엘라스틱서치) 입문
 
대용량 분산 아키텍쳐 설계 #5. rest
대용량 분산 아키텍쳐 설계 #5. rest대용량 분산 아키텍쳐 설계 #5. rest
대용량 분산 아키텍쳐 설계 #5. rest
 
Web App Security 2015.10
Web App Security 2015.10Web App Security 2015.10
Web App Security 2015.10
 
Http 완벽 가이드(2장 url과 리소스)
Http 완벽 가이드(2장 url과 리소스)Http 완벽 가이드(2장 url과 리소스)
Http 완벽 가이드(2장 url과 리소스)
 
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요
DGMIT 제3회 R&D 컨퍼런스 r&d1 team : HTTP 프로토콜 개요
 
03. HTTPS & Restful
03. HTTPS & Restful03. HTTPS & Restful
03. HTTPS & Restful
 
HTTP 발표자료 - 김연수
HTTP 발표자료 - 김연수HTTP 발표자료 - 김연수
HTTP 발표자료 - 김연수
 
OWASP TOP 10 in 2007
OWASP TOP 10 in 2007OWASP TOP 10 in 2007
OWASP TOP 10 in 2007
 
IT 일반기술 강의자료_ed10
IT 일반기술 강의자료_ed10IT 일반기술 강의자료_ed10
IT 일반기술 강의자료_ed10
 
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취
[2017 Incognito] Hack the AIR;카페에서 ARP 스푸핑을 통한 세션 탈취
 
Http 헤더
Http 헤더Http 헤더
Http 헤더
 
Web server
Web serverWeb server
Web server
 
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)
ASP.NET 4.0 New Features Part2 - URL Routing(ASP.NET WebForms)
 
REST with Spring
REST with SpringREST with Spring
REST with Spring
 
Http 완벽가이드(3장 http 메시지)
Http 완벽가이드(3장 http 메시지)Http 완벽가이드(3장 http 메시지)
Http 완벽가이드(3장 http 메시지)
 
[APL OJT] REST API TEST
[APL OJT] REST API TEST[APL OJT] REST API TEST
[APL OJT] REST API TEST
 
2Naver Open Android API Translation At DCamp
2Naver Open Android API Translation At DCamp2Naver Open Android API Translation At DCamp
2Naver Open Android API Translation At DCamp
 
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)
Http2(http2.0,g rpc,cookie,session,idempotent, x forwarded-for)
 

Restful API guide

  • 1. RESTful API Design Guide 김 병 부 (Benjamin Kim) byungboor@naver.com http://myboor.tistory.com
  • 2. Introspection • Resource의 나열 – RESTful의 본질 외면 – CRUD 제외한 operation 에 대한 어려움 – 수많은 Resource • 보안상 문제점 – Key exchange – 메시지 암호화 X – Error 메시지의 난립 – HTTP Resource에 노출된 정보들 • 통일된 Guide 없이 임기 응변 • OpenAPI가 될 수 없다.
  • 3. Table of Contents • RESTful API fundamental concept • Use RESTful URLs and actions • Error Handling • Security • HATEOAS (optional) • Reference Link
  • 4. RESTful API fundamental concept • Resource – HTTP URL format • Method – HTTP Standard Methods for CRUD operations – POST - Create – GET - Read – DELETE - Delete – PUT - Update • Message – XML, YAML, JSON and HTML format HTTP POST, /instances { “instance” : { “name” : “xmyboor001”, “specId” : “x1.large” } }
  • 5. Use RESTful URLs and actions #1 • 명사를 사용한다. • 복수형을 사용한다. • 구체적인 이름을 사용한다. – (O) HTTP GET /instances – (O) HTTP GET /instances/1024 – (O) HTTP GET /instances/sdcconsoledb01 – (X) HTTP GET /instance – (X) HTTP GET /instances?id=1024 – (X) HTTP GET /getInstance • 예외상황 – CRUD를 제외한 다른 명령어는 어떻게? – E.g. Chef의 Role을 실행하는 경우 (O) HTTP POST /role/2048/run (X) HTTP GET /role/run?instanceId=1024&roleId=2048
  • 6. Use RESTful URLs and actions #2 • 리소스간 관계는 sub-resource를 사용한 다. – HTTP GET /instances/1024/volumes/204 – HTTP POST / instances/1024/volumes • Paging은 limit, offset 키워드를 사용한 다. – Facebook Style – HTTP GET /instances?offset=100&limit=30 • Partial Response (Optional) – Facebook Style – HTTP GET /instances?field=instanceId,name • ER Diagram – Table Instance and Volume
  • 7. Use RESTful URLs and actions #3 Resource GET Read POST Create PUT Update DELETE /instances Returns a list of instances Create a new Instance Bulk update of instances Delete all instances /instances/1024 Returns a specific instance Method not allowed (405 error) Updates a specific instance Delete a specific instance /instances/1024/vol umes Returns a list of volumes of the instance Create a new volume at the instance Bulk update of volumes at the instance Delete all volumes at the instance /instances/1024/vol umes/204 Return a specific volume of the instance Method not allowed (405 error) Update a specific volume at the instance Delete a specific volume at the instance
  • 8. Use RESTful URLs and actions #4 • Searching – 파라미터 이름 ‘q’를 이용한다. – q=name=myboor004,zone=qa&limit=30 – URLEncode 를 사용한다. – HTTP GET /instences?q=name%3Dmyboor004,zone%3D=qa&limit=30 • Sorting – 파라미터 이름 ‘sort’ 를 이용한다. – 기호 ‘-’ descending – 기호 ‘+’ ascending – HTTP GET /instences?sort=-instanceId,+
  • 9. Use RESTful URLs and actions #5 • Version – Mandatory – REST Resource에 정의하는 방법, HTTP Header에 정의 하는 방법 등이 있음 – Resource 에 정의 한다. – HTTP GET /sdc/api/v1.0/instances • HTTP headers for serialization formats – Client, Server 모두 format을 지정해야 한다. – Format은 HTTP-Header의 context-type 을 사용한다. – 기본적으로 JSON format을 사용한다. MessageType Content-Type JSON application/json
  • 10. Use RESTful URLs and actions #6 • eXtended headers for REST API – 다음과 같은 customized 된 추가 헤더를 사용한다. – Mandatory or 401 error – Client Side Header Name Description X-NETMARBLE-LOGINID 로그인 아이디 정보 X-NETMARBLE-CHANNEL OpenAPI에 접속하는 Channel 정보
  • 11. Error Handling #1 • Error 처리는 HTTP Status Code를 사용한다. • 약 70여 개의 HTTP Status Code가 존재 – http://en.wikipedia.org/wiki/Http_error_codes • 다음과 같은 방식으로 HTTP Status Code를 사용한다. – 200 - OK : 성공 (동기식) – 201 - OK : 성공 (비동기식) – 400 - Bad Request : Parameter validation 실패, Json 포멧 에러 – 401 - Unauthorized : 인증 실패 – 403 – Forbidden : 인가 실패 – 404 - Not Found – 410 - Gone : 요청된 resource가 더 이상 존재하지 않을때 발생하는 에러. – 500 - Internal Server Error : 서버 측 에러
  • 12. Error Handling #2 • Error Payload – HTTP Status code 만으로 충분한 메시지가 전달되기 힘들다. – 서버에서는 다음과 같은 format으로 response body에 응답한다. HTTP Status Code : 401 { “status” : “401”, “userMessage” : “Authentication Failure”, “errorCode” : “30201”, “errorInfo” : “http://sdn/wiki/errors/30201” } – 단 2XX code에서는 payload가 필요없다. – Exception Stack 정보를 포함하지 않는다.
  • 13. Security #1 • 인증 (Authentication) – REST API를 호출하는 대상을 확인하는 절차 • 인가 (Authorization) – REST API의 resource를 사용할 권한이 있는지 확인하는 절차 • 네트워크 레벨의 암호화 – 네트워크 프로토콜 단의 암호화. – HTTPS 를 사용한다. • 메시지 무결성 보장 – 메시지 변조를 방지하기 위해서, 메시지의 Hash Code를 비교하여 메시지 무결성을 확인 • 메시지 본문 암호화 – 네트워크 레벨의 암호화를 사용 못하는 경우, 메시지 본문을 암호화한다.
  • 14. Security #2 • Authentication – Basic Authentication 은 가능한 피한다. 계정와 암호를 Base64 인코딩하므로 디코딩 가능함. – Token 방식의 digest algorithm – HMAC-SHA256 – Use OAuth 1.0a or Oauth 2 • API Key를 사용 – Entropy – Reduced Exposure – Traceability – Avoid Sessions – Authenticate every request
  • 15. Security #3 • API Access Token 인증방법 – Use HTTPS – Token exchange using Secure Cookie https://www.owasp.org/index.php/SecureFlag – Access token is valid within expireTime – 조대협님 블로그 (http://bcho.tistory.com/955)
  • 16. Security #4 • REST API Message Policy in Spring MVC – Controller, Service, Dao – ValueObject – Table Record와 일치 > ValueObject 를 JSON 포멧으로 마샬링할 때, 중요한 데이터까지 사용자에게 노출된다. – DomainObject for JSON Message – Controller Layer에서 marshalling, unmarshalling 하기 위해서 Domain 객체를 사용한다.
  • 17. HATEOAS (optional) • HATEOAS – Hypermedia as the engine of application state – HTTP Response에 다음 action에 관한 링크를 제공 – E.g. detail 링크를 제공하는 경우 – E.g. paging 링크를 제공하는 경우 HTTP GET /instances?limit=30&offset=30 { “rows” : [ {“instanceId” : 1024, “name” : “sdcconsoledb01”}, {“instanceId” : 1025, “name” : “sdcconsoledb02”} ], “links” : [ {“rel” : “prev”, “href” : “http://sdc/instances?limit=30&offset=0”}, {“rel” : “next”, “href” : “http://sdc/instances?limit=30&offset=60”} ] }
  • 18. Reference Link • http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/ • http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api • http://restful-api-design.readthedocs.org/en/latest/resources.html • http://www.slideshare.net/stormpath/secure-your-rest-api-the-right-way • http://bcho.tistory.com/914 • http://bcho.tistory.com/953 • http://bcho.tistory.com/955