[좋은 API 디자인이란 무엇일까] - REST API 의 6가지 제약사항

최근에 사내 스터디로 "일상 속 사물이 알려주는 웹 API" 책을 동료들과 함께 읽었었는데 API 설계에 대해서 한번 더 생각 해 볼수 있는 기회가 되어서 좋았었다. 

 

이 책에서는 API 설계는 "프로바이더" 관점이아닌 "컨슈머"의 관점이 되어야 한다고 강조하고 있다.

"컨슈머" 관점인 좋은 API 설계를 구성하기 위해서는 아래 6가지 제약사항을 잘 이해하고 있어야 한다.

 

* 클라이언트 / 서버 분리

* 스테이트 리스

* 캐시 가능성

* 레이어드 시스템

* 코드 온 디맨드

* 유니폼 인터페이스

 

1. 클라이언트 / 서버 분리 (서로 의존하면 안됨)

모바일 애플리케이션의 동작 방식과 서버의 동작 방식에 대해서 분리하여 생각해야한다.

클라이언트는 서버의 구체적인 동작을 알 수 없어야하고 (API URL만 알고있어야 함) 서버도 클라이언트의 구체적인 동작을 알 수 없다. 각자의 역할만 잘 수행하도록 한다. 

 

2. 스테이트 리스

요청을 처리하는데 필요한 모든 정보는 해당 리퀘스트에 포함되어 있어야 한다. 서버는 클라이언트의 그 어떠한 컨택스트도 저장하고 있으면 안된다.

 

3. 캐시 가능성

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control 

리퀘스트에 대한 리스폰스는 저장 가능 여부를 표시해줘야 한다. 클라이언트가 동일한 요청에 대해 데이터를 재 사용함으로써 요청-응답 과정에서 latency를 줄일 수 있다.

 

4. 레이어드 시스템

우리가 클라이언트로 부터 요청을 받아도 아래와 같은 구조일때는 단순히 depth 가 1인 통신이 아닌 2이상의 통신일수도 있다. 

 

위와 같은 구조에서도 클라이언트는 오직 depth1 서버의 API URL 만 알아야 한다. 

 

5. 코드 온 디맨드 (선택사항)

개발을 하다보면 서버가 실행가능한 무엇인가를 클라이언트에 제공할 경우가 생길 수 있다.

예를들어 비밀번호를 잃어버렸다고 가정해보자, 비밀번호 초기화를 위해서 등록된 이메일에 인증 메일을 요청받았고,링크를 클릭하여 비밀번호 변경을 할 수 있는 웹페이지를 받는 플로우가 있다. 

 

이때 우리는 HTML + Javascript 코드를 서버로 부터 제공받아서 조작한다.

 

6. 유니폼 인터페이스

모든 클라이언트 - 서버 상호작용은 리소스의 개념에 따라서 이루어져야함, 시스템의 자원은 논리적으로 오직 한개의 URL 로 나타낼 수 있어야하며 자원의 모든 정보는 API 통신 인터페이스를 통해 알 수 있어야함, 모든 자원은 너무 크면 안되며 만약 연관된 자원을 표현할 경우가 생길 때 (Pagination) 다음 자원의 링크를 포함해서 응답해야함 (HATEOAS)

 

오늘은 Representational State Transfer 스타일을 이해하기 위한 6가지 제약조건 사항을 간단히 알아보았다. 앞으로 좋은 API 를 위해 알아야하는 지식을 알때마다 블로그에 정리할 예정이다.

 

 

참고자료

https://restfulapi.net/rest-architectural-constraints/#client-server

 

 

글에서 틀린부분, 궁금한 부분들 있으면 언제든 답글 달아주세요! 저도 배워가는 입장인지라 정확한 정보가 아닐수 있습니다 :)