RESTful API를 설계하기 위한 디자인 팁

2013년 06월 11일 | 유병석

안녕하세요. 스포카 개발팀 유병석입니다. 오늘 포스팅에서는 저번에 스포카 기술 블로그에 올라왔었던 REST 아키텍처를 훌륭하게 적용하기 위한 몇 가지 디자인 팁의 글에서 언급되지 않았던 추가적인 내용에 대해서 좀 더 얘기해보고자 합니다. 혹시 이전 포스팅을 읽지 않으셨다면 이전 포스팅을 먼저 읽으신 후 이 포스팅을 읽어주시기 바랍니다.

Document?

컬렉션에 관해서는 앞서 소개한 이전 글에서 자세히 설명해놓았으니 읽어보시기 바랍니다. 지금 제가 언급할 것을 도큐먼트인데요. 도큐먼트는 컬렉션과는 달리 단수명사나 명사의 조합으로 표현되어 URI에 나타납니다.

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio

위의 예제에서 leauges라는 컬렉션 리소스가 있는 것을 알 수 있습니다. 그 컬렉션의 자식 리소스 중 하나가 seattle이라는 리소스인데요, 바로 이 리소스가 도큐먼트입니다. 도큐먼트는 하위 계층으로 또 컬렉션을 가질 수 있습니다. 이 예제에서의 teams가 seattle의 자식 컬렉션 리소스가 되겠지요. 즉, 단수 리소스는 도큐먼트라 칭하고 복수 리소스는 컬렉션으로 칭한다고 알아두시면 됩니다.

이 URI는 또한 문서의 계층 구조를 표현하고 있습니다. 즉 슬래시 기호(/) 다음으로 나타내는 명사가 그 앞에 나오는 명사의 자식 계층이 되는 것이지요. 이러한 도큐먼트의 응답으로써, 요청에서 명시된 Content-Type 헤더에 1:1대응하는 응답을 주는 것이 의미 있을 때가 있습니다. 가령,

URI : dogs/1

1) Content-Type: application/json
2) Content-Type: application/xml
3) Content-Type: application/png

이와 같은 URI에 3개의 요청이 주어졌고, 각각 Content-Type이 다음과 같을 때 어떤 응답이 보내져야 할까요? 물론, 그것은 응답을 설계한 사람의 맘이지만 일반적인 기준을 적용해본다면 1번과 2번 요청에는 각각 json, xml 형식으로 구조화된 데이터가 그리고 3번 요청에 대해서는 해당 강아지의 사진이 담긴 png 파일을 보낼 수 있을 것입니다. 또한, Content-Type에 대해서 명시하여 원하는 리소스를 선택할 수 있으므로 URI 내에는 파일 확장자를 포함하지 않는 것이 좋습니다.

dogs/1.xml 

위와 같은 URI를 만드는 것보다,

dogs/1
 
위의 URI에 Content-Type: application/xml헤더를 포함하여 요청을 보내는 것이 더 적절한 선택입니다.

어째서 파일에 확장자를 붙이지 않는 것이 더 나은 선택일까요? URI는 고유한 리소스를 나타내는 데 쓰여야 합니다. 그런데 URI에 확장자를 붙이는 순간 마치 다른 리소스인 것처럼 느껴집니다. 확장자를 달리하여 같은 리소스에 대한 다른 표현 양식을 주문하는 것이지 해당 리소스가 달라지는 것은 아닙니다. 또한, URI에 직접 확장자가 붙게 되면 해당 리소스 URI가 응답으로 지원하는 확장자만큼 새로운 URI들이 생기게 되겠지요. 결코, 이것은 좋은 디자인이 아닙니다.

Controller?

기본으로 GET, PUT, POST, DELETE 요청에 1:1매치 되는 개념인 CRUD가 있습니다. CRUD의 앞글자들을 풀어보면 Create, Read, Update, Delete가 될 텐데, 각각 POST, GET, PUT, DELETE에 대응되는 개념입니다. 그런데 사실 URI를 디자인 하다 보면 이러한 방식으로 나타내기 참 어려운 경우를 많이 만나게 됩니다. 그 중 가장 많은 경우가 어떤 특정한 행위를 요청하는 경우입니다. 많은 분이 이럴 때 동사를 쓰는데, 앞선 포스팅에서 밝혔듯이 동사를 써서 URI를 디자인하는 것은 대체로 옳지 않은 방식으로 여겨집니다.

이럴 때 컨트롤러 리소스를 정의하여 이 문제를 해결할 수 있습니다. 컨트롤러 리소스는 URI 경로의 제일 마지막 부분에 동사의 형태로 표시되어 해당 URI를 통해 접근했을 때 일어날 행위를 생성합니다. (개념적으로는 이렇게 받아들이시면 됩니다.) 생성과 관련된 요청이 POST이기 때문에 컨트롤러 리소스에 접근하려면 POST 요청을 보내야 합니다. 예제를 살펴보시면 이해하기 빠르실 겁니다.

http://api.college.restapi.org/students/morgan/register
리소스 morgan을 등록

http://api.ognom.restapi.org/dbs/reindex
리소스 dbs를 재색인

http://api.build.restapi.org/qa/nightly/runTestSuite
리소스 nightly에 테스트를 수행

그리고 마치 프로그램의 함수처럼 컨트롤러 리소스에는 입력값을 전달할 수 있습니다. 그것은 POST 요청의 엔티티 바디에 포함되어야 합니다. 그리고 역시 함수에서 반환값을 돌려주듯이 컨트롤러 리소스에서는 해당 입력 값에 대한 응답 값을 돌려주면 되겠습니다.

URI 뒤에 붙는 쿼리의 용도

흔히 GET 요청을 보낼 때 뒤에 추가로 쿼리 스트링(?,=,& 기호를 이용하여)을 전달하곤 합니다. 여기서는 그 쿼리 스트링을 어떻게 디자인 하는 게 좋은지에 대한 논의와 함께 실제 서비스에서 사용되는 사례를 살펴봅니다.

가령 특정 컬렉션 리소스에 대하여 질의를 보낼 때 그 컬렉션의 집합이 너무 거대할 수 있으므로 필요한 정도의 정보만을 요구하기 위해서 페이징 값 혹은 구분 값을 쿼리 스트링에 포함할 수 있습니다. 예를 들어 보면

/resources?pageSize=10&pageStartIndex=0

페이징을 위한 정보 전달

/dogs?color=red&state=running&location=park

구체적인 검색 제약사항 전달

이런 식으로 써서 페이징을 한다든가 혹은 다른 파라메터(color=red)따위를 던져서 검색 범위를 제한할 수 있습니다. 흔히 쿼리 스트링을 저런 용도로 많이 사용하기 때문에 아마 관찰력이 좋으신 분들은 저런 종류의 쿼리 파라메터를 네이버, 구글 같은 포털사이트의 검색 서비스를 이용하시면서 본 적이 있으실 것입니다.

이와는 약간 다르게 실제 DB에서 사용하는 SQL의 select 문과 같은 결과를 낼 수 있도록 돕는 쿼리 스트링을 URI에 나타내려는 시도도 많은 편인데요. 물론 SQL에서 제공하는 구문의 모든 의미를 다 제공할 필요는 없겠지만, 기본적으로 서비스에서 필요한 정도의 인터페이스를 적절히 제공한다면 사용자가 선택할 수 있는 옵션이 많아진다는 측면에서 좋은 방법이겠죠. 이와 관련된 예제를 몇 개 소개하겠습니다. 이것은 실제 서비스에서 API로 제공되었던 URI들입니다. 구조나 의미가 SQL 문과 상당히 유사합니다.

LinkedIn
/people:(id,first-name,last-name,industry)
이 경우 people 리소스를 요청하되 마치 SQL 쿼리에서 가져올 필드를 제한하는 것처럼 필요한 필드에 대해서만 괄호로 묶어서 지정한 것을 볼 수 있습니다.

Facebook
/joe.smith/friends?fields=id,name,picture
이 경우 이름(혹은 계정이름)이 joe.smith인 사람의 정보를 가져오되 LinkedIn의 예와 같이 필드를 제한(id,name,picture)해서 가져오도록 한 예입니다.

Google
?fields=title,media:group(media:thumbnail)
구글도 마찬가지네요. 이쯤 오면 대략 저 URI가 무엇을 의미하는지 알아채셨으리라 생각합니다.

URI 설계시에 주의해야 할 점

URI에는 소문자를 사용해야 합니다. 왜냐하면, RFC 3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이지요.

http://api.example.restapi.org/my-folder/my-doc
HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc

위의 두 URI는 같은 URI입니다. 호스트에서는 대소문자를 구별하지 않기 때문이지요.

http://api.example.restapi.org/my-folder/my-doc
http://api.example.restapi.org/My-Folder/my-doc

하지만 위의 두 URI는 다른 URI입니다. 뒤에 붙는 path가 대소문자로 구분되기 때문입니다.

물론 소문자가 아닌, 대소문자를 섞어 쓰거나 혹은 대문자만 쓰는 것도 가능하지 않으냐는 반론이 나올 수 있습니다. 하지만 대소문자를 섞어 쓰면 URI를 기억하기 어려울 뿐만 아니라 실제 사용 시 실수하기 쉽다는 단점이 있습니다. 만약 대문자만 쓴다면 상관은 없겠으나 일반적으로는 URI에 대문자를 잘 쓰지 않기 때문에 소문자로 쓰는 것을 권장합니다.

HTTP HEADER

HTTP 요청과 응답을 보낼 때 특정 헤더를 포함해 요청, 응답 그리고 리소스에 대한 메타 정보를 전달할 수 있습니다. 요청 헤더와 응답 헤더에 포함되면 좋을 만한 헤더 정보들에 대하여 알아보겠습니다.

요청 헤더

Accept

응답으로 받고 싶은 미디어 타입을 명시하기 위하여 사용됩니다. 예제를 들어 설명하겠습니다.

GET /magna-opus HTTP/1.1
Host: example.org
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 

이 요청은 mangna-opus 리소스에 대해서 기본적으로는 html이나 xhtml의 형식으로 응답을 받고 싶되, 만약 상황이 여의치 않으면 xml을 만약 그것도 여의치 않다면 모든 응답(*/*)을 받아들이겠다는 것을 말합니다. 옆에 붙은 q가 선호도를 나타내게 되지요. (q 생략 시 1값을 가짐) 만약 앞의 예에서 모든 응답에 대한 표시가 없다고 가정하고 서버에서 앞의 세 가지 미디어 타입을 모두 지원할 수 없는 상황이라면 응답으로 406 상태코드를 내보내야 합니다.

Accept-Charset

응답으로 받고 싶은 캐릭터셋에 대하여 명시하는 헤더입니다.

Accept-Charset: iso-8859-5, unicode-1-1;q=0.8

가령 위의 예제는 일단 iso-8859-5를 선호하지만 unicode-1-1도 괜찮다는 메시지를 전달합니다.

User-Agent

현재 요청을 보낸 Agent의 정보를 표시하기 위해 사용됩니다.

User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0

파이어폭스 버전 21.0의 UA스트링, OS에 대한 정보도 담겨져있다.

Referer

해당 요청을 보내기 바로 직전에 참조하던 리소스 혹은 주소에 대한 정보를 나타내기 위해 사용합니다.

Referer: http://en.wikipedia.org/wiki/Main_Page

응답 헤더

Content-Length

요청과 응답 메시지의 엔티티 바디가 얼마나 큰지에 대한 정보를 나타내기 위해 사용합니다. 단위는 바이트입니다.

Content-Length: 348

Last-Modified

해당 리소스가 마지막으로 갱신된 시간을 나타내기 위하여 사용됩니다. 캐싱 정책과 관련되어 중요한 헤더중 하나입니다.

Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT

캐시나 쿠키정책과 관련된 헤더 정보는 글의 분량을 고려하여 생략하였지만, 매우 중요한 헤더 중 하나이므로 다른 관련 문서들을 검색하여 일독을 권합니다.

HTTP 상태 코드

의미에 잘 맞는 URI를 설계하는 것도 중요한 일이지만 그 리소스에 대한 응답을 잘 내어주는 것 또한 중요한 일입니다. 그런데 혹시 HTTP의 상태코드 중 200이나 404코드 정도만 알고 계시지 않으신가요? 그 코드의 정확한 의미를 얘기하실 수 있으신가요? 사실 저도 흔하게 볼 수 있는 상태코드 몇 개 정도만 알고 있고 나머지 상태코드의 정확한 의미라든지 쓰임새에는 관심이 별로 없었던 것이 사실이었습니다. 하지만 전문적으로 웹 개발의 길을 걸어갈 사람이라면 그보다는 좀 더 자세히, 많이 알고 있을 필요가 있겠지요. 사실 우리가 생각하는 것보다 훨씬 많은 상태코드가 존재하고 각각 그 쓰임이 다 다릅니다. 그 중 몇 개를 살펴보겠습니다.

200 : OK

일반적인 요청 성공을 나타내는 데 사용합니다. 단, 주의해야 할 점이 있다면 200코드를 에러 응답에 사용하면 안 된다는 것입니다. 가령 코드는 200인데 에러메시지를 포함한다든가 하면 의미에 맞지 않은 응답코드를 보낸 것이겠지요. 이런 적절치 못한 상황을 처리하는 경우에는 4XX대 코드를 사용하여야 합니다.

201 : Created

리소스 생성 성공에 대한 응답 코드입니다. CRUD 요청에서 Create 요청에 대한(즉, 컬렉션에 도큐먼트 추가 같은) 응답으로 내보낼 수 있는 응답코드입니다. 응답 헤더의 Location 필드에 생성된 리소스에 접근할 수 있는 URI를 포함할 수 있다면 브라우저에서 그 값을 참조하여 적절히 대응할 수 있겠습니다.

202 : Accepted

대체로 처리 시간이 오래 걸리는 비동기 요청에 대한 응답으로 사용됩니다. 즉, 이 요청에 대한 응답이 결과를 포함하지 않을 수 있다는 것이죠. 하지만 최소한 응답 헤더나 응답데이터에 해당 처리를 모니터링할 수 있는 리소스 페이지를 안내하거나 혹은 해당 리소스가 처리되기까지의 예상 경과 시간 따위를 안내하는 것이 더 좋은 설계라고 할 수 있겠습니다.

301 : Moved Permanently

리소스가 이동되었을 경우의 응답코드입니다. 새로 리소스가 이동된 URI를 응답 Location 헤더에 명시해야 합니다. 이 응답을 받은 클라이언트는 새 URI로 이동하든지 아니면 URI를 갱신하고 캐싱을 한다든지 하는 행위를 해야 되겠지요.

400 : Bad Request

일반적인 요청실패에 사용합니다. 대체로 서버가 이해할 수 없는 형식의 요청이 왔을 때 응답하기 위해 사용됩니다. 무턱대고 400에러를 응답으로 주지 말고, 다른 4XX대의 코드가 더 의미를 잘 설명할 수 있는지에 대하여 고민해야 합니다.

401 : Unauthorized

말 그대로 리소스 접근 권한을 가지고 있지 않다는 것을 의미하기 위한 응답코드입니다. 리소스를 획득하기 위하여 요청자는 인증에 필요한 헤더(가령 Authorization 헤더 같은)나 데이터를 첨부해야 할 것입니다. 필요한 헤더나 데이터는 서버 쪽에서 요구하는 스펙을 충실히 따라야겠지요.

403 : Forbidden

감춰진 리소스에 접근하려 할 때의 응답코드입니다. 401과 달리 인증의 여부와 관계없이 리소스를 보여주지 않습니다. 기본적으로 클라이언트 쪽에 정보를 공개하고 싶지 않은 리소스임을 나타내기 위해 사용합니다.

404 : Not Found

해당 URI와 매치되는 리소스가 없다는 의미를 전달합니다. 어지간한 사람들은 다 한 번씩(?) 마주치게 되는 응답코드이지요.

405 : Method Not Allowed

지원하지 않는 요청(예를 들어 POST 요청을 받는 컨트롤러 리소스에 GET 요청을 보낸다든가)을 하였을 때 사용합니다. 가능하다면 응답 메시지에 Allow 헤더를 추가하고 그곳에 지원하는 메서드를 명시하여 클라이언트 측에서 정확한 요청을 보낼 수 있도록 유도합니다.

Allow: GET, POST

406 : Not Acceptable

해당 미디어 타입(MIME 타입)에 대해서 지원하지 않을 때 사용합니다. 요청 Accept 헤더에 명기된 타입(가령 Application/xml)에 대해서 지원이 불가능할 경우에 돌려주면 되는 코드입니다.

409 : Conflict

요청의 형식에는 문제가 없지만 리소스 상태에 의하여 해당 요청 자체를 수행할 수 없는 경우의 응답코드입니다. 즉, 이미 삭제된 리소스를 또 삭제한다든가 비어있는 리스트에서 무언가를 요청한다든가 하는 모순된 상황을 생각해보면 되겠습니다. 응답으로는 그 방법을 어떻게 해결할 수 있을지에(혹은 문제가 무엇인지) 대한 힌트가 포함되면 좋을 것입니다.

500 : Internal Server Error

일반적인 서버 에러에 대한 응답코드입니다. 4XX대의 에러코드가 클라이언트 측 에러를 나타내기 위해 사용된다면, 5XX대의 에러코드는 서버 측 에러를 나타내기 위해 사용됩니다.

503 : Service Unavailable

가장 두려운(?) 응답코드 중 하나일 503입니다. 현재 서버에 과부하가 걸려있거나 유지보수를 위하여 잠시 접근이 거부될 때 필요한 응답코드입니다.

그냥 맨 앞의 숫자별로 퉁쳐서 상태코드를 내보내지 않고, 이렇게 디테일한 의미까지 따져가면서 상태코드를 내보내는 것에 대해서 그 효용성에 의문을 제기하시는 분들이 있을 것 같습니다. 하지만 브라우저에서 혹은 서버 단에서 특정 상태코드에 대해서 내부 구현을 달리하거나 최적화를 통해 더 쾌적한 환경을 제공할 가능성이 있으므로 되도록 의미에 걸맞은 상태코드를 사용하는 것을 생활화하는 것이 중요합니다. 또한, 이렇게 디테일한 상황을 가정하고 만든 URI들이 다음에 서비스를 확장할 때 큰 도움이 될 것임은 의심할 여지가 없겠지요.

위에서 소개한 응답 코드 말고 또 다른 응답 코드들에 대해서도 전부 소개해 놓은 링크를 밑에 달아두었으니 참고하시기 바랍니다.

정리

지금까지 소개한 내용이 조금은 두서없게 느껴졌을 수도 있겠다는 생각이 들어 한 번 전체 내용 정리를 해보려 합니다.

컨트롤러의 정확한 쓰임을 알고 적절한 컨트롤러 URI를 구현하자.
URI에 추가로 붙게 되는 쿼리 스트링의 형식을 잘 디자인하여 사용자로 하여금 적재적소에 쓸 수 있도록 하자.
가능하다면 이용 가능한 HTTP 헤더를 적절하게 첨가하자.
HTTP 상태코드의 의미에 대해서 생각해보고 상황에 맞는 적절한 상태 코드를 응답으로 보내줄 수 있도록 하자.

이 글을 쓰면서 한빛 미디어의 일관성 있는 웹 서비스 인터페이스 설계를 위한 REST API 디자인 규칙과 apigee사의 web API design eBook을 참고하였습니다. 둘 다 내용이 좋은 서적이고 이 글에서 다루지 않은 심층 내용을 다루니 기회가 되시면 읽어보세요.

references

스포카에서는 “식자재 시장을 디지털화한다” 라는 슬로건 아래, 매장과 식자재 유통사에 도움되는 여러 솔루션들을 개발하고 있습니다.
더 나은 제품으로 세상을 바꾸는 성장의 과정에 동참 하실 분들은 채용 정보 페이지를 확인해주세요!