주제선정 이유
REST API 를 알아봄으로써, API 제작시 주로 사용되는 패턴등을 알아볼 수 있었습니다.
내용REST API 발표 문서
REST API에 대한 발표를 시작하겠습니다.
api
먼저, 간단하게 API의 개념을 간단하게 정리하겠습니다.
‘API는 응용프로그램에서 사용할 수 있도록, 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스입니다.’
보시는 내용은 위키피디아 사전에 있는 설명을 그대로 가져온것입니다.
다들 아시는 개념이지만, 처음 보시는 분은 이런 설명에 대해 혼란을 느끼실 수 있습니다.
먼저, 좀 더 접근하기 쉬운 UI를 집고 넘어가겠습니다.
UI는 user Interface의 약자로 사용자입장에서 컴퓨터의 브라우저 및 프로그램을 조작하는 데 있어서, 중간매체의 하는 역할을 하는 수단, 방법을 말합니다.
API도 같은 맥락으로 볼 수 있는데, UI는 프로그램과 사용자를 이어주는 매개체라면, API는 프로그램과 프로그램를 이어주는 역할을 한다고 볼수 있습니다.
RESTful
RESTful에 대해 알아보겠습니다.
RESTful은 일반적으로 REST라는 아키텍처를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어입니다.
예를들어 REST API를 제공하는 웹서비스를 RESTful하다고 할 수 있습니다.
또한, RESTful은 공식적으로 발표된 것이 아니기 때문에, REST원리를 따르는 시스템은 RESTful이라 합니다.
RESTful한 api를 구현하는 목적은 성능 향상에 있는 것이 아니라, api의 이해도와 호환성을 높이는 것입니다.
때문에 성능이 중요한 경우는 굳이 RESTful한 API를 구현할 필요가 없습니다.
다음은 RESTful하지 못한 경우입니다.
개념
그럼 본격적으로 REST API에 대한 내용으로 들어가 보겠습니다.
REST는 웹의 창시자(HTTP)중의 한 사람인 Roy Fielding의 2000년 논문에 의해서 소개되었습니다.
현재의 아키텍처가 웹의 본래 설계의 우수성을 많이 사용하지 못하고 있다고 판단했기 때문에, 웹의 장점을 최대한 활용할 수 있는 네트워크 기반의 아키텍처를 소개했는데,
그것이 바로 REST입니다.
REST의 요소로는 크게 3가지로 구성되는 데 크게 리소스, 메서드, 메시지로 구성됩니다.
예를 들어서 “이름이 홍길동인 사용자를 생성한다.”라는 호출이 있을때,
“사용자”는 생성되는 리소스, “생성한다”는 행위, “이름이 홍길동인 사용자를 생성한다”는 메시지가 됩니다.
화면의 예시를 보시면, REST의 기본적인 형태를 보여주고 있는데,
생성한다의 의미를 갖는 메서드는 HTTP Post 메서드가 되고,
생성하고자 하는 사용자의 디테일한 내용은 JSON 문서를 이용해서 표현된 것입니다.
REST는 HTTP메서드를 그대로 사용하는데, 그중 CRUD에 해당하는 4가지의 메서드만을 사용합니다.
표를 보시면 메서드가 CRUD에 서로 대응되는 보실 수 있고, Idempotent는 여러 번 수행해도 결과가 같은 경우를 의미합니다.
Idempotent는 a++과 같이 호출시마다 가변적인 값은 Idempotent하지 않은 경우고, a=4와 같이 고정적인 값은 Idempotent하다고 합니다.
Idempotent가 중요한 이유는 REST는 각 개별 API를 상태 없이 수행하게 되는데, 해당 REST API를 다른 API와 함께 호출하다가 실패하였을 경우,
트렌젝션 복구를 위해 다시 실행하는 경우가 있습니다.
Idempotent는 한 메서드들은 반복적으로 다시 메서드를 실행하면 되지만,
그렇지 않은 메서드들은 다시 원상복귀를 해줘야 된다는 차이점이 있습니다.
예를 들어 게시물 조회를 하는 API가 있을때, 조회시 마다 조회수를 올리는 연산을 수행한다면, 이 메서드는 Idempotent 하다고 볼수 없으며,
조회가 실패하였을시, 조회수를 다시 -1로 빼줘야 합니다.
즉, Idempotent 하지 않은 메서드에 대해서는 트렉젠션에 대한 처리를 주의해서 사용해야 합니다.
REST는 리소스 지향 아키텍쳐 스타일이라는 정의 답게 모든 것을 명사로 표현하며, 각 세부 리소스에는 id를 붙입니다.
REST 리소스가 명사형으로 띄우다 보니, 명령성의 API를 정의하는것에 혼돈이 올 수 있습니다.
예를들어 “push한 메시지를 보낸다”를 /myweb/sendpush 형태로 잘못 정의될 수 있는데,
POST/myweb/push 형태와 같이 명사형으로 정의 될 수 있습니다.
물론 모든 형태의 명령이 이런 형태로 정의가 가능한 것은 아니지만, 되도록이면 리소스 기반의 명사형태로 정희하는게 REST형태의 디자인이 됩니다.
다음은 REST 사용예제입니다.
첫번째 예시는 myweb/users 라는 리소스를 이름은 홍길동, 주소는 서울 이라는 내용(메시지)로 HTTP Post를 이용해서 생성하는 정의입니다.
그 다음 차례대로 myweb/use 라는 리소스에서 id가 홍길동인 사용자 정보를 조회, 수정, 삭제하는 방법입니다.
단순하게 리소스를 URI로 정해준 후에, HTTP 메서드를 이용해서 CRUD를 구현하고 메시지를 JSON으로 표현하여 HTTP BODY에 실어 보내면 됩니다.
특성,안티패턴
다음순서로 REST의 특성과 안티패턴들을 정리해 보았습니다.
설계
그럼, 본격적으로 REST API의 설계에 대해 알아보겠습니다.
디자인가이드
먼저 REST API 디자인 가이드입니다.
첫번째, URI는 정보의 자원을 표현해야 합니다.
예시를 보시면, 리소스명에 delete와 같이, 행위를 나타내는 동사표현이 사용되었는데, 이와 같은 표현은 들어가서는 안됩니다.
두번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현됩니다.
위에 잘못된 예시를 REST의 올바른 규칙대로 수정한다면, 이와같이 수정할 수 있겠습니다.
다음으로 URI 설계시 주의할점입니다.
첫번째, 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용합니다.
예시를 보시면 집 -> 아파트, 동물 -> 포유류 -> 고래 와 같은 계층을 나타내는데 슬래시 구분자를 사용합니다.
두번째, URI 마지막 문자로 슬래시(/)를 포함하지 않습니다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고,
역으로 리소스가 다르면 URI도 달라져야 합니다. REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않습니다.
세번째 하이픈(-)은 URI 가독성을 높이는데 사용합니다.
불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높인다.
네번째 밑줄(_)은 URI에 사용하지 않습니다.
글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 합니다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋습니다. (가독성)
다섯번째 URI경로에는 소문자가 적합합니다.
URI 경로에 대문자 사용은 피하도록 해야합니다.
대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다.
RFC3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문입니다.
여섯번째 파일 확장자는 URI에 포함시키지 않습니다.
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI안에 포함시키지 않습니다. Accept header를 사용합니다.
다음은 리소스간의 관계를 표현하는 방법입니다.
REST 리소스간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법을 사용합니다.
(예1)
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다.
예를들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수있습니다.
(예2)
컬렉션과 도큐먼트
다음은 자원을 표현하는 Collection과 Document에 대해 알아보겠습니다.
Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워집니다. DOCUMENT는 단순히 문서로 이해해도 되고,
한 객체라고 이해하셔도 될 것 같습니다.
컬렉션은 문서들의 집합, 객체들의 집합이라고 생각하시면 이해하시는데 좀더 편하실 것 같습니다.
컬렉션과 도큐먼트는 모두 리소스라고 표현할 수 있으며 URI에 표현됩니다. 예를 살펴보도록 하겠습니다.
첫번째 예시를 보시면 sports라는 컬렉션과 soccer라는 도큐먼트로 표현되고 있는 URI가 있습니다.
좀더 예를 들어보자면 두번째 예시는 컬렉션과 도큐먼트를 복수로 사용하고 있습니다.
Sports, players 컬렉션과 soccer, 13 도큐먼트로 URI가 이루어지게 됩니다.
이와같이 좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할때 단수 복수도 지켜준다면 좀더 이해하기 쉬운 URI를 설계 할 수 있습니다.
에러처리
다음은 에러처리에 대해 알아보겠습니다.
먼저, HTTP 응답상태 코드에 대해 표로 간단히 정리해 보았습니다.
에러처리의 기본은 HTTP Response Code를 사용한 후, Response body에 error detail을 서술하는 것이 좋습니다.
대표적인 API 서비스들과 일반적으로 사용되는 응답상태코드들을 정리해보았습니다.
그밖에 API 사용예시
이 외에 API 사용예시를 정리해보았습니다.
문제점
마지막으로 REST의 취약점에 대해 알아보겠습니다.
첫번째로 REST는 표준 규약이 없습니다.
때문에, 제대로된 REST API의 가이드와, API 개발 전후로 API 문서(Spec)을 제대로 만들어서 리뷰하는 프로세스를 갖추는 방법으로 해결해야 합니다.
두번째로는 기존의 전통적인 RDBMS에 적용시키기 쉽지 않다는 것입니다.
예를 들어 리소스를 표현할 때, 리소소는 DB의 하나의 ROW가 되는 경우가 많은데, DB의 경우는 기본키가 복합키형태로 존재하는 경우가 많습니다.
HTTP URI에서는 슬래시에 따른 계층 구조를 가지기 때문에, 이에 대한 표현이 매우 부자연스러워 집니다.
이 외에도 리소스에 대한 유니크한 키를 부여하는 것 등의 애로사항을 가지고 있습니다.
그래서 근래에 나온 mongoDB나 Document based NoSQL를 사용해 JSON 객체를 그대로 넣을 수 있는 구조를 갖추어,
맵핑하기가 수월해 지게 하는 방법이 있습니다.
이상으로 REST API 세미나 발표를 마치겠습니다.