REST API에 대해 - 2

이전 글 : https://developthreefeet.tistory.com/3

REST API에 대해 - 1 (feat, URI, URL, URN)

이번엔 REST API 규격에 맞춰 어떻게 API 인터페이스를 작성하면 좋을 지 이야기해 보겠습니다. 

 

인터페이스가 표현할 웹 페이지의 기능은 간단하게 할 일 목록 수정이라고 하겠습니다. 

저같은 경우, REST API 개념이 없는 상태에서는 보통 이런 식으로 작성했습니다. 

 

HTTP POST - http://localhost/tasks/update

 

이러한 형태의 API는 REST API에서 말하는 자원 개념을 충실히 적용했다고 볼 수 없습니다.

update라는 단어는 자원이라기 보다는 특정한 행동이라고 보는 게 더 타당하기 때문이죠. 

 

그럼 REST를 적용한다면 어떻게 해야 할까요?

해당 기능의 목적을 조금 더 명확히 정의한다면 답이 나올 수도 있습니다. 

이 기능의 목적은 가지고 있던 할 일 목록 중 하나의 할일을 수정하는 것이라고 볼 수 있습니다.  

그렇다면 이런 형태는 어떨까요?

 

HTTP POST http://localhost/tasks/1 

 

이렇게 보니 이전보다는 자원 개념이 조금 더 명확하게 표현된 것 같습니다.

여기서 알 수 있는 점은 REST API를 적용할 때는 URI를 주로 명사 형태로 작성하는 것이 좋다는 것입니다. 아무래도 동사 형태의 단어는 자원이라고 말하기가 쉽지 않지요. 

 

그렇지만 이 방법 역시 문제점이 존재합니다. 

 

HTTP POST http://localhost/tasks/1 

 

이러한 인터페이스는 자원 개념은 명확히 표시되지만, 정작 이것만 보면 자원을 새로 생성하는 것인지, 수정하는 것인지, 혹은 삭제하는 것인지 명확치 않습니다. 이 때 도움이 되는 개념이 바로 메소드(Method) 입니다. 

 

메소드는 HTTP 프로토콜에서 URI에 표시된 자원을 어떻게 할 지에 대한 행위를 표현하는 방법입니다. 우리가 위에서 제거한 update가 의미 상에서는 메소드에 더 적합하다고 볼 수 있죠. 사실 HTTP 메소드는 여러가지 용도에 따라 어느정도 규격화가 되어 있습니다. 

HTTP Method	전송형태	설명
GET	GET [request-uri]?query_string HTTP/1.1	요청받은 URI의 정보를 검색하여 응답한다.
HEAD	HEAD [request-uri] HTTP/1.1	GET방식과 동일하지만, 응답에 BODY가 없고 응답코드와 HEAD만 응답한다.
POST	POST [request-uri] HTTP/1.1	요청된 자원을 생성(CREATE)한다. 새로 작성된 리소스인 경우 HTTP헤더 항목 Location : URI주소를 포함하여 응답.
PUT	PUT [request-uri] HTTP/1.1	요청된 자원을 수정(UPDATE)한다. 내용 갱신을 위주로 Location : URI를 보내지 않아도 된다. 클라이언트측은 요청된 URI를 그대로 사용하는 것으로 간주함.
PATCH	PATCH [request-uri] HTTP/1.1	PUT과 유사하게 요청된 자원을 수정(UPDATE)할 때 사용한다. PUT의 경우 자원 전체를 갱신하는 의미지만, PATCH는 해당자원의 일부를 교체하는 의미로 사용.
DELETE	DELETE [request-uri] HTTP/1.1	요청된 자원을 삭제할 것을 요청함.  (안전성 문제로 대부분의 서버에서 비활성)
CONNECT	CONNECT [request-uri] HTTP/1.1	동적으로 터널 모드를 교환, 프락시 기능을 요청시 사용.
TRACE	TRACE [request-uri] HTTP/ 1.1	원격지 서버에 루프백 메시지 호출하기 위해 테스트용으로 사용.
OPTIONS	OPTIONS [request-uri] HTTP/ 1.1	웹서버에서 지원되는 메소드의 종류를 확인할 경우 사용.

이러한 HTTP 메소드들은 크게 2가지의 유형을 가지고 있습니다. 두 유형 중 하나를 적용한다고 다른 유형을 적용시키지 못하는 것은 아닙니다. 

1. safe(수행 시 안전 여부) : GET, HEAD에 적용됨

2. Idempotent(여러번 수행해도 결과가 같은 것) : POST, PATCH 를 제외한 나머지 메소드들에 적용됨

 

safe의 경우는 해당 메소드를 수행해도 자원에 대해 영향을 끼치지 않는다는 것을 의미합니다. 즉 안전하다는 것이죠. 때문에 자원 조회 혹은 기능 테스트의 경우에 많이 사용됩니다. 

 

그렇다면 만약에 할일 목록 중 하나를 삭제하는 API를 GET방식으로 실행하면 어떻게 될까요?

아마도 이런 형태일 것입니다.

 

HTTP GET - http://127.0.0.1/tasks/1/delete

 

이 API를 적용하면 safe한 메소드임에도 불구하고 해당 할일은 삭제됩니다.  

HTTP METHOD는 어디까지나 코딩 컨벤션의 영역이기에, 서버 단에서 작성한 코드의 결과에는 손을 댈 수 없어 GET으로 접근했음에도 데이터가 삭제되는 것이죠. 

때문에 HTTP 메소드를 선택할 때는 약간 조심해야 할 필요성이 있습니다. 

위와 같이 delete나 update 같은 자원에 영향을 주는 기능임에도 불구하고 메소드를 GET으로 사용한다면, 그 페이지에 접속하는 사람 혹은 시스템이 GET 메소드를 보고 안전하다고 판단하고 별 거리낌없이 들어가볼 수 있기 때문이죠. 그러므로 기능에 걸맞는 메소드를 사용하는 것이 중요합니다. 

 

Idempotent는 위에서도 설명을 했지만 같은 API를 여러 번 수행해도 그 결과가 일정하다는 뜻을 내포하고 있습니다. 예를 들어 Idempotent한 GET 메소드는 아무리 여러번 수행해도 서버 코드가 변하지 않는 한 그 결과가 똑같죠. 

하지만 POST의 경우는 어떨까요? POST는 위 표에 따르면 자원을 생성하는 메소드이니, 똑같은 API더라도 여러번 실행하면 첫 실행 때 첫번째 자원을 생성하고 두번째 실행 때 두번째 자원을 생성하는 등 다른 결과를 보여줄 것입니다. 

 

여기서 이상한 점이 있습니다. PUT과 PATCH는 같은 수정 메소드임에도 왜 PUT은 idenpotent하고, PATCH는 그렇지 않은 것일까요? 

 

사실 대부분의 경우에는 PATCH도 idempotent하다고 볼 수 있습니다. 다만 특수한 상황이 존재할 때가 있죠. 

PATCH는 자원의 전부가 아닌 일부 특성을 수정하는 메소드입니다. 그렇다면 이런 경우가 있을 수 있습니다.

 

HTTP PATCH -  http://127.0.0.1/tasks/1/?change=name&from=kane&to=john

 

이 API는 자원의 이름을 kane에서 john으로 바꾸라는 명령입니다. 

이 API를 처음 실행하면 정상적으로 kane에서 john으로 바뀌겠지만, 두 번째 실행에서는 정상적으로 작동하지 않을 수 있습니다. 왜냐하면 kane에서 john으로 바꿔야 하는데 자원의 현재값이 kane이 아닌 john으로 바뀌어 버렸기 때문이죠 (이전의 API 실행이 원인입니다). 

이런 점에서 PATCH가 idempotent하지 않다는 결론이 나온 것입니다. 

 

일반적으로는 GET 과 POST 를 많이 사용하지만 그 외에도 목적에 따라 다양한 형태의 메소드를 사용할 수 있습니다. 

여기서 배운 메소드들을 적용한다면 위의 할일 목록 수정 API를 개선할 수 있습니다. 지금은 자원(tasks) 중 일부(1)를 수정하는 것이니 PATCH를 적용하는 것도 좋겠네요. 

 

HTTP PATCH http://localhost/tasks/1 

 

이렇게 REST API의 가장 기본적인 형태를 만들어 보았습니다. 실제로 API를 설계할 때 REST API를 엄격하게 적용하는 곳이 그렇게 많지는 않지만, 그렇다고 완전히 모르거나 놓고 가서는 안되는 개념이기에 개인적으로라도 정리를 해 보았습니다. 

 

감사합니다. 

 

-끝-