Restful 한 API 디자인에 대해

동사보다는 명사를 사용하자

URL을 심플하고 직관적으로 만들자

REST API를 URL만 보고도, 직관적으로 이해할 수 있어야 한다
URL을 길게 만드는것 보다, 최대 2 depth 정도로 간단하게 만드는 것이 이해하기 편하다.

/dogs
/dogs/1234

URL에 동사보다는 명사를 사용한다.

REST API는 리소스에 대해서 행동을 정의하는 형태를 사용한다. 예를 들어서

POST /dogs

는 /dogs라는 리소스를 생성하라는 의미로, URL은 HTTP Method에 의해 CRUD (생성,읽기,수정,삭제)의 대상이 되는 개체(명사)라야 한다.
잘못된 예들을 보면

HTTP Post : /getDogs
HTTP Post : /setDogsOwner

위의 예제는 행위를 HTTP Post로 정의하지 않고, get/set 등의 행위를 URL에 붙인 경우인데, 좋지 않은 예 이다. 이보다는

HTTP Get : /dogs
HTTP Post : /dogs/{puppy}/owner/{terry}

를 사용하는 것이 좋다.
일반적으로 권고되는 디자인은 다음과 같다.

리소스	POST	GET	PUT	DELETE
	create	read	update	delete
/dogs	새로운 dogs 등록	dogs 목록을 리턴	Bulk로 여러 dogs 정보를 업데이트	모든 dogs 정보를 삭제
/dogs/baduk	에러	baduk 이라는 이름의 dogs 정보를 리턴	baduk이라는 이름의 dogs 정보를 업데이트	baduk 이라는 이름의 dogs 정보를 삭제

단수(Singular) 보다는 복수(Plural)형 명상를 사용한다.

되도록이면 추상적인 이름보다 구체적인 이름을 사용하자

리소스간의 관계를 표현하는 방법

Option A.

다른 리소스와의 관계를 표현. 예를 들어 owner가 가지고 있는 개(dogs) 목록

GET /owner/{terry}/dogs

와 같이 /resource명/identifier/other-related-resource 형태로, 해당 리소스에 대한 경로를 /resource명/{그 리소스에 대한 identifier}/{연관되는 다른 리소스 other-related-resource} 형태로 표현한다.

Option B.

https://usergrid.incubator.apache.org/docs/relationships/ 에 보면 다른 형태의 관계 정의 방법에 대해서 나와 있는데, 조금 더 구체적인 API 관계 정의 방법은 다음과 같다.

/resource/identifier/relation/other-related-resource
GET /owner/terry/likes/dogs

리소스간의 관계가 복잡하지 않은 서비스의 경우에는 Option A를, 리소스간의 관계가 다소 복잡한 경우에는 Option B를 사용하도록 한다.

" style="margin: 1em 0px; word-wrap: break-word; color: rgb(0, 0, 0); font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', AppleSDGothicNeo-Medium, 'Segoe UI', 'Malgun Gothic', Verdana, Tahoma, sans-serif; font-size: 11px; line-height: normal;">이 방식은 리소스간의 관계(relationship)을 URL 내에 정의하는 방법으로,훨씬 더 명시적일 수 있다. (세련되어 보이지는 않지만)
리소스간의 관계가 복잡하지 않은 서비스의 경우에는 Option A를, 리소스간의 관계가 다소 복잡한 경우에는 Option B를 사용하도록 한다.

에러 처리

에러 처리의 기본은 HTTP Response Code를 사용한후, Response body에 error detail을 사용해주는 것이 좋다.

Use HTTP Status Code

HTTP Status Code는 대략 70개의 코드가 있다. 일반적인 개발자들이 모든 코드를 기억할리는 없고, 에러 코드에서는 자주 사용되는 몇개의 코드만 의미에 맞춰서 사용하는 것이 좋다.
Google의 GData의 경우에는 10개, Neflix의 경우에는 9개, Digg의 경우에는 8개를 사용한다.
(※ http://info.apigee.com/Portals/62317/docs/web%20api.pdf)

• Google GData
  200 201 304 400 401 403 404 409 410 500
• Netflix
  200 201 304 400 401 403 404 412 500
• Digg
  200 400 401 403 404 410 500 503

필자의 경우, 아래와 같은 정도의 HTTP Code를 사용하기를 권장한다.

• 200 성공
• 400 Bad Request - field validation 실패시
• 401 Unauthorized - API 인증,인가 실패
• 404 Not found
• 500 Internal Server Error - 서버 에러

자세한 HTTP Status Code는 http://en.wikipedia.org/wiki/Http_error_codes 를 참고하기 바란다.

Error Message

HTTP Status Code 이외에, Response body에 detail한 에러 정보를 표현하는 것이 좋은데,
Twillo의 Error Message 형식의 경우

HTTP Status Code : 401
{“status”:”401”,”message”:”Authenticate”,”code”:200003,”more info”:”http://www.twillo.com/docs/errors/20003"}

와 같이 표현하는데, 에러 코드 #와 해당 에러 코드 #에 대한 Error dictionary link를 제공한다.
비단 API 뿐 아니라, 잘 정의된 소프트웨어 제품의 경우에는 별도의 Error # 에 대한 Dictionary 를 제공하는데, Oracle의 WebLogic의 경우에도http://docs.oracle.com/cd/E24329_01/doc.1211/e26117/chapter_bea_messages.htm#sthref7 와 같이 Error #와, 이에 대한 자세한 설명과, 조치 방법등을 설명한다. 이는 개발자나 Trouble Shooting하는 사람에게 많은 정보를 제공해서, 조금 더 디버깅을 손쉽게 한다. (가급적이면 Error Code #를 제공하는 것이 좋다.)

Error Stack

에러메세지에서 Error Stack 정보를 출력하는 것은 대단히 위험한 일이다. 내부적인 코드 구조와 프레임웍 구조를 외부에 노출함으로써, 해커들에게, 해킹을 할 수 있는 정보를 제공하기 때문이다. 일반적인 서비스 구조에서는 아래와 같은 에러 스택정보를 API 에러 메세지에 포함 시키지 않는 것이 바람직 하다.

log4j:ERROR setFile(null,true) call failed.
java.io.FileNotFoundException: stacktrace.log (Permission denied)
at java.io.FileOutputStream.openAppend(Native Method)
at java.io.FileOutputStream.(FileOutputStream.java:177)
at java.io.FileOutputStream.(FileOutputStream.java:102)
at org.apache.log4j.FileAppender.setFile(FileAppender.java:290)
at org.apache.log4j.FileAppender.activateOptions(FileAppender.java:164)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)

그렇지만, 내부 개발중이거나 디버깅 시에는 매우 유용한데, API 서비스를 개발시, 서버의 모드를 production과 dev 모드로 분리해서, 옵션에 따라 dev 모드등으로 기동시, REST API의 에러 응답 메세지에 에러 스택 정보를 포함해서 리턴하도록 하면, 디버깅에 매우 유용하게 사용할 수 있다.

버전 관리

API 정의에서 중요한 것중의 하나는 버전 관리이다. 이미 배포된 API 의 경우에는 계속해서 서비스를 제공하면서,새로운 기능이 들어간 새로운 API를 배포할때는 하위 호환성을 보장하면서 서비스를 제공해야 하기 때문에, 같은 API라도 버전에 따라서 다른 기능을 제공하도록 하는 것이 필요하다.
API의 버전을 정의하는 방법에는 여러가지가 있는데,

• Facebook ?v=2.0
• salesforce.com /services/data/v20.0/sobjects/Account
  필자의 경우에는

  {servicename}/{version}/{REST URL}
  example) api.server.com/account/v2.0/groups

형태로 정의 하는 것을 권장한다.
이는 서비스의 배포 모델과 관계가 있는데, 자바 애플리케이션의 경우, account.v1.0.war, account.v2.0.war와 같이 다른 war로 각각 배포하여 버전별로 배포 바이너리를 관리할 수 있고, 앞단에 서비스 명을 별도의 URL로 떼어 놓는 것은 향후 서비스가 확장되었을 경우에, account 서비스만 별도의 서버로 분리해서 배포하는 경우를 생각할 수 있다.
외부로 제공되는 URL은 api.server.com/account/v2.0/groups로 하나의 서버를 가르키지만, 내부적으로, HAProxy등의 reverse proxy를 이용해서 이런 URL을 맵핑할 수 있는데, api.server.com/account/v2.0/groups를 내부적으로 account.server.com/v2.0/groups 로 맵핑 하도록 하면, 외부에 노출되는 URL 변경이 없이 향후 확장되었을때 서버를 물리적으로 분리해내기가 편리하다.

페이징 처리와 Partial response

페이징

큰 사이즈의 리스트 형태의 응답을 처리하기 위해서 필요한 것은 페이징 처리와 partial response 처리이다. 리스트 내용이 1000,000개인데, 이를 하나의 HTTP Response로 처리하는 것은 서버 성능, 네트워크 비용도 문제지만 무엇보다 비현실적이다. 그래서, 페이징을 고려하는 것이 중요하다.
페이징을 처리하기 위해서는 여러가지 디자인이 있다.

예를 들어 100번째 레코드부터 125번째 레코드까지 받는 API를 정의하면

• Facebook API 스타일 : /record?offset=100&limit=25
• Twitter API 스타일 : /record?page=5&rpp=25 (RPP는 Record per page로 페이지당 레코드수로 RPP=25이면 페이지 5는 100~125 레코드가 된다.)
• LikedIn API 스타일 : /record?start=50&count=25

apigee의 API가이드를 보면 좀더 직관적이라는 이유로 페이스북 스타일을 권장하고 있다.
record?offset=100&limit=25

Partial Response (Optional)

리소스에 대한 응답 메세지에 대해서 굳이 모든 필드를 포함할 필요가 없는 케이스가 있다. 예를 들어 페이스북 FEED의 경우에는 사용자 ID, 이름, 글 내용, 날짜, 좋아요 카운트, 댓글, 사용자 사진등등 여러가지 정보를 갖는데, API를 요청하는 Client의 용도에 따라 선별적으로 몇가지 필드만이 필요한 경우가 있다. 필드를 제한하는 것은 전체 응답의 양을 줄여서 네트워크 대역폭(특히 모바일에서) 절약할 수 있고, 응답 메세지를 간소화하여 파싱등을 간략화할 수 있다.
그래서 몇몇 잘 디자인된, REST API의 경우 이러한 Partial Response 기능을 제공하는데, 주요 서비스들을 비교해보면 다음과 같다.

• Linked in : /people:(id,first-name,last-name,industry)
• Facebook : /terry/friends?fields=id,name
• Google : ?fields=title,media:group(media:thumnail)
  Linked in 스타일의 경우 가독성은 높지만 :()로 구별하기 때문에, HTTP 프레임웍으로 파싱하기가 어렵다. 전체를 하나의 URL로 인식하고, :( 부분을 별도의 Parameter로 구별하지 않기 때문이다.
  Facebook과 Google은 비슷한 접근 방법을 사용하는데, 특히 Google의 스타일은 더 재미있는데, group(media:thumnail) 와 같이 JSON의 Sub-Object 개념을 지원한다.
  Partial Response는 Google 스타일을 이용하는 것을 권장한다.

검색

검색은 일반적으로 HTTP GET에서 Query String에 검색 조건을 정의하는 경우가 일반적인데, 이 경우 검색조건이 다른 Query String과 섞여 버릴 수 있다. 예를 들어 name=cho이고, region=seoul인 사용자를 검색하는 검색을 Query String만 사용하게 되면 다음과 같이 표현할 수 있다.
/users?name=cho&region=seoul
그런데, 여기에 페이징 처리를 추가하게 되면

/users?name=cho&region=seoul&offset=20&limit=10

페이징 처리에 정의된 offset과 limit가 검색 조건인지 아니면 페이징 조건인지 분간이 안간다. 그래서, 쿼리 조건은 하나의 Query String으로 정의하는 것이 좋은데

/user?q=name%3Dcho,region%3Dseoul&offset=20&limit=10

이런식으로 검색 조건을 URLEncode를 써서 “q=name%3Dcho,region%3D=seoul” 처럼 (실제로는 q= name=cho,region=seoul )표현하고 Deleminator를 , 등을 사용하게 되면 검색 조건은 다른 Query 스트링과 분리된다.
물론 이 검색 조건은 서버에 의해서 토큰 단위로 파싱되어야 하낟.

전역 검색과 리소스 검색

다음으로는 검색의 범위에 대해서 고려할 필요가 있는데, 전역 검색은 전체 리소스에 대한 검색을, 리소스에 대한 검색은 특정 리소스에 대한 검색을 정의한다.
예를 들어 시스템에 user,dogs,cars와 같은 리소스가 정의되어 있을때,id=’terry’인 리소스에 대한 전역 검색은

/search?q=id%3Dterry

와 같은 식으로 정의할 수 있다. /search와 같은 전역 검색 URI를 사용하는 것이다.
반대로 특정 리소스안에서만의 검색은

/users?q=id%3Dterry

와 같이 리소스명에 쿼리 조건을 붙이는 식으로 표현이 가능하다.

HATEOAS (Optional)

HATEOS는 Hypermedia as the engine of application state의 약어로, 디자인의 요지는 하이퍼미디어의 특징을 이용하여 HTTP Response에 다음 Action에 대한 HTTP Link를 함께 리턴하는 것이다.
예를 들어 앞서 설명한 페이징 처리의 경우, 리턴시, 전후페이지에 대한 링크를 제공한다거나

HTTP GET users?offset=10&limit=5
{
[
{‘id’:’user1’,’name’:’terry’}
,{‘id’:’user2’,’name’:’carry’}
]
,’links’ :[
{
‘rel’:’pre_page’,
‘href’:’http://xxx/users?offset=6&limit=5‘
}
,
{
‘rel’:’next_page’,
‘href’:’http://xxx/users?offset=11&limit=5‘
}
]
}
와 같이 표현하거나
연관된 리소스에 대한 디테일한 링크를 표시 하는 것등에 이용할 수 있다.
HTTP GET users/terry
{
‘id’:’terry’
‘links’:[{
‘rel’:’friends’,
‘href’:’http://xxx/users/terry/friends‘
}]
}

HATEOAS를 API에 적용하게 되면, Self-Descriptive 특성이 증대되어 API에 대한 가독성이 증가하는 장점을 가지고 있기는 하지만, 응답 메세지가 다른 리소스 URI에 대한 의존성을 가지기 때문에, 구현이 다소 까다롭다는 단점이 있다.
요즘은 Spring과 같은 프레임웍에서 프레임웍 차원에서 HATEOAS를 지원하고 있으니 참고하기 바란다.http://spring.io/understanding/HATEOAS

단일 API URL

API 서버가 물리적으로 분리된 여러개의 서버에서 동작하고 있을때, user.apiserver.com, car.apiserver.com과 같이 API 서비스마다 URL이 분리되어 있으면 개발자가 사용하기 불편하다. 매번 다른 서버로 연결을 해야하거니와 중간에 방화벽이라도 있으면, 일일이 방화벽을 해제해야 한다.
API 서비스는 물리적으로 서버가 분리되어 있더라도 단일 URL을 사용하는 것이 좋은데, 방법은 HAProxy나 nginx와 같은 reverse proxy를 사용하는 방법이 있다.
HAProxy를 앞에 새우고 api.apiserver.com이라는 단일 URL을 구축한후에
HAProxy 설정에서

api.apiserver.com/user는 user.apiserver.com 로 라우팅하게 하고
api.apiserver.com/car 는 car.apiserver.com으로 라우팅 하도록 구현하면 된다.

보안

API 서비스에 있어서 보안은 매우 중요한 요소이다. API 에 대한 보안은 다음과 같이 보안 대상에 따라서 몇가지로 나눠진다.

인증

인증은, API를 호출하는 클라이언트가 VALID한 사용자인지, 불법적인 사용자인지를 구별하는 방식이다.

HTTP Basic Auth

가장 쉬운 방식으로는 사용자 id,password를 표준 HTTP Basic Auth에 넣어서 전송하는 방식으로 사용자 단위의 인증과 권한 컨트롤이 가능하다는 장점을 가지고 있다. 그러나 이 경우, 매번 사용자 id와 password가 네트워크를 통해서 전송되기 때문에, 해커에 의해서 사용자 id,password가 누출될 수 있다. 사용자 id,password가 누출되면 API 호출 권한뿐만 아니라 웹에 로그인해서 다른 서비스를 사용하는 등 치명적이기 때문에 그리 권장되지 않는 방법이다.
SSL을 사용해서 암호화할 수 는 있겠지만 기본적으로 SSL은 Man in the middle attack (중간에 인증서를 가로체서 SSL 패킷을 열어보는 방법) 에 취약하기 때문에 완벽하다고 볼 수 없다.

Access Token

매번 네트워크를 통해서 사용자 id,password를 보내는 것이 위험하다면, 처음 인증시에만 id,password를 보내고, 인증이 성공하면 서버에서 access_token을 발급하여 API 호출시 access_token으로만 호출하는 방식이다. (OAuth2.0이 유사한 메커니즘을 사용한다.) 이 경우 API를 호출하는 클라이언트가 access_token을 저장하는 메카니즘을 가져야 한다. 또한 access_token이 누출될때를 대비하여, 서버쪽에서 compromised된 (노출된/오염된) token의 경우 revoke(사용금지 처리)를 하고, 클라이언트에게 다시 access_token을 발급하도록 하는 메커니즘과, Expire time을 둬서 주기적으로 token을 교체하도록 하는 방식이 좋다.

API Key

API Key 시나리오는 일반적으로 API 제공자가 API 포탈등을 통해서, 개발자를 인증하고 개발자에게 API Key를 발급한후, 개발자가 API Key를 애플리케이션 코드내에 탑재해서 사용하는 방법을 사용한다. API를 외부 파트너에게 공개하는 경우에 손쉽게 사용할 수 있으며, 꽤 많이 사용되던 방식이다. 단 애플리케이션 (특히 모바일 애플리케이션)이 디컴파일 될 경우 API Key가 누출될 수 있는 위험성을 가지고 있기 때문에, API Key를 잘 관리 하는 것이 중요하다. (난독화를 한다던가)
이 시나리오의 경우 애플리케이션 단위의 인증을 하기 때문에 앞서 설명한 두 방식처럼 사용자 단위의 인증은 불가능 하다.
(사용자 단위의 인증이 필요한 경우 API Key로 애플리케이션을 인증한 후에, 클라이언트 마다 새로운 access_token을 발급하는 방식을 사용할 수 있다. 사실 이게 OAuth 2.0의 client_secret과 access_token 시나리오와 유사하다.)

OAuth 2.0 (Recommended)

OAuth는 근래에 가장 많이 사용되는 API 인가/인증 기술이다. 특징중의 하나는 Authentication(인증)만이 아니라 권한에 대한 통제(Authorization)이 가능하다는 특징을 가지고 있으며, 3 legged 인증을 통해서, 파트너사가 API를 사용할 경우, 인증시에 사용자 ID와 비밀번호를 파트너에게 노출하지 않을 수 있는 장점이 있다. (페이스북 계정을 이용한 웹 애플리케이션들을 보면 가끔, 페이스북 로그인 화면으로 리다이렉트되어 “XX 애플리케이션이 XX에 대한 권한을 요청합니다. 수락하시겠습니까?”와 같은 창이 뜨는 것을 볼 수 있는데, 페이스북 로그인 화면에, 사용자 ID와 비밀 번호를 넣고 페이스북은 인증이 되었다는 정보를 인증을 요청한 웹애플리케이션으로 보내서, 해당 사용자가 인증되었음을 알려준다. 이경우, 웹 애플리케이션은 사용자의 비밀번호를 알 수 없다. )
기본적인 OAuth의 원리는, 사용자 ID/PASSWD로 인증을 한 후에, access_token을 받아서, access_token을 이용해서 추후 커뮤니케이션을 하는 방식이다.

OAuth는 크게 용도에 따라 4가지 타입의 인증 방식을 제공한다.

• Authorization Code 방식 - 주로 웹 애플리케이션 인증에 유리하며, 위에서 설명한 케이스와 같이 웹을 통해서 Redirect 하는 방식이다.
• Implicit 방식 - 자바스크립트 기반의 애플리케이션이나 모바일 애플리케이션 처럼 서버 백엔드가 없는 경우 사용한다.
• Resource Owner password credential 방식 - 인증을 요청하는 클라이언트에서 직접 ID와 PASSWD를 보내는 방식으로, (이 경우 위의 방식들과 다르게 서비스 제공자의 로그인창으로 리다이렉션이 필요 없다.) 클라이언트가 직접 ID,PASSWD를 받기 때문에, 클라이언트에 사용자의 비밀번호가 노출될 수 있어서 서버와 클라이언트를 같은 회사에서 제작한 경우나, 사용자의 정보를 공유해도 되는 1’st party 파트너등과 같은 경우에 사용한다.
• Client Credential 방식 - 일반적인 애플리케이션 Access에 사용한다.

일반적으로 API를 3’rd party에 제공할 경우에는 Authorization Code 방식을, 자사의 API를 자사나 1’st party 파트너만 사용할 경우에는 Resource Owner password credential 방식이 좋다.

Mutual SSL

가장 강력한 인증 방법으로,클라이언트와 서버가 각자 인증서를 가지고 상호 인증하는 방식이다. 양방향(2-way)SSL 이라고도 한다. 이 경우에는 클라이언트의 인증서(Certificate)를 서버에게 안전하게 전송할 수 있는 메커니즘이 필요하다. 클라이언트가 접속했을때, Certificate를 네트워크를 통해서 전송하고, 서버는 이 인증서가 공인된 인증서인지를 확인하는 방법도 있고, 내지는 서버의 Admin Console등을 통해서 클라이언트가 사용하는 인증서 자체를 업로드 해놓는 방법등 다양한 방법이 있다.
Mutual SSL은 양쪽에 인증서를 사용하기 때문에, Man in the middle attack이 불가능하고, Packet을 snipping해서 보는 것 조차도 불가능 하다. (대신 구현이 다소 까다롭다.)

WhiteList 방식

서버간의 통신에서는 가장 간단하게 할 수 있는 방식이 서버가 API 호출을 허용할 수 있는 IP 목록을 유지하는 방법이다. (WhiteList 방식). 다른 IP에서 들어오는 API 호출의 경우 받지 않는 방법으로, 가장 구현이 간단하다. 방화벽이나 Reverse proxy 설정등으로도 가능하고, 필요하다면, VPN (Virtual Private Network)등을 이용할 수 도 있다.

프로토콜 레벨 암호화

HTTP 통신 프로토콜 자체를 암호화 하는 방식인데, SSL을 이용한 HTTPS가 대표적인 경우이다. API 디자인에서 HTTPS는 반드시 적용하는 것을 권장한다.
HTTPS는 앞에서도 잠깐 언급했듯이 Man in the middle attack에 취약한데 Man in the middle attack의 기본적인 메커니즘은 서버에서 보낸 인증서를 바꿔치기 해서, 클라이언트로 보내는 방식을 이용한다. (http://en.wikipedia.org/wiki/Man-in-the-middle_attack)
가능하면, 인증서 체크 로직을 클라이언트에 두는 것이 좋다. 인증서가 공인된 인증서인지, (또는 그 서버의 인증서가 맞는지를 Issuer등을 통해서 확인할 수 있다. 인증서에 있는 내용들은 기본적으로 중간에 해커가 바꿀 수 다 없다. Signing이 되어있기 때문에, 내용을 바꾸면 Singing된 Signature가 맞지 않는다.) attack

메세지 레벨 암호화

다음으로 JSON과 같은 메세지 자체를 암호화할 수 있는데, 앞서 설명해듯이 SSL을 사용하더라도, 중간에 인증서를 바꿔 치는 등의 행위를 통해서 패킷을 열어볼 경우, 메세지 내용을 노출될 가능성이 있기 때문에 이를 방지 하기 위해서, 중요한 메세지는 암호화하는 것을 권장한다.
이때 전체 메세지를 암호화 하는 것은 비효율적이며 특정 필드의 값만 필요에 따라서 암호화를 하는 것이 좋다.

출처 : http://bcho.tistory.com/914