1부에서 REST API의 핵심인 http 프로토콜에 대한 전반적인 내용을 다루었다. 2부에서는 REST API를 효율적으로 설계하는 방법들에 대해 소개한다. 해당 포스트는 Two Scoops of Django의 16장 REST API 구현하기를 요약하여 작성하였다.


1. API 컴포넌트를 어디에 위치시킬까?

API를 구현하는 것 자체는 비교적 수월하게 끝냈다고 하더라도 이러한 API를 하나의 프로젝트 내에서 관리하는 최적의 구조를 생각하기란 쉽지 않다. 새로운 API가 추가될 경우나 버전 관리를 할 경우에는 어떤 코드가 어디에 위치하느냐가 중요해진다.

작은 규모의 프로젝트

제작해야할 API의 규모가 작은 대신 다양할 경우에는 작은 앱들이 여러 개 포함된 프로젝트가 생성된다. 이럴 때는 차라리 프로젝트의 모든 API 관련 코드(시리얼라이저, 렌더러, 뷰 등)가 하나의 앱 내에 위치하는 것이 훨씬 더 좋은 방법이다. 이러한 앱의 이름은 버전명으로 관리하여 버전별로 API를 관리할 수도 있다.

그러나 이러한 구조는 API만 모아놓은 앱의 크기가 커졌을 때 문제가 될 수 있다. 따라서 프로젝트가 더이상 커지지 않을 경우(기능이 추가되지 않을 경우)에 적합하다고 할 수 있다. 또, API만 모아놓는 앱을 만들게 되면 API 관련 코드를 포함하지 않은 앱으로부터 리소스를 임포트해야할 경우 꼬이지 않게 주의해야한다.


큰 규모의 프로젝트

하나의 views 모듈에 담기에 API가 너무 많은 경우에는 views 폴더를 생성하여 뷰클래스를 모듈별로 분할하는 것이 좋다. 하지만 이 경우 작게 나뉜 모듈들이 많아지면 혼란스럽고 관리하기 피곤해질 수 있다. 이 때는 뷰클래스의 크기와 갯수에 따라 적당히 위의 방법을 사용하는 것도 좋다.


2. API 뷰에서 로직은 빼자

뷰는 요청에 대한 페이지를 렌더해준다. 뷰에 비지니스 로직을 추가하게 되면 REST API를 생성할 경우 새로운 기능을 추가할 때마다 그에 맞춰서 코드를 반복수정해야한다. 대신 모델의 메서드매니저 메서드로 로직을 컴포넌트화하여 뷰에서 호출해 사용하는 방식으로 변경하는 것이 코드의 확장 및 재사용성 측면에서 좋다. 장고의 뷰에서 기본적으로 사용하는 로직 이외에 비지니스 로직은 뷰 밖에서 처리하도록 한다.


3. API URL 구조는 하나의 URL로 묶어놓자

앱을 여러 개 만들어 작업하다보면 view들은 각각의 앱마다 생성하여 관리된다. view들이 앱마다 분산되어 있으므로 view를 호출하는 url을 한 군데에 모으는 방법으로 로직을 합칠 수 있다. 다음 예제를 보자.

# core/api.py
urlpatterns = [
	url(
	r'^api/', 
	include("core.api", 
	namespace="api")
	),
]

위의 패턴은 core.api 파일 안에 있는 모든 url 앞에 api/를 붙여 하나의 로직으로 묶어주는 역할을 한다. 이렇게 API 관련 URL만 모아서 정리해두면 버저닝이 훨씬 편리하다. API 업데이트시 하나로 묶어주는 패턴만 변경해주면 되기 때문이다.


4. API 버저닝을 생활화하자

테스트를 진행할 경우, 작업한 API 별로 버전을 나누어두는 게 편리하다. 이는 API의 URL에 버전 정보를 표시하는 것으로 간단하게 처리할 수 있다.

예를 들면 첫 url을 /api/v1/flavors/로 지정할 경우 다음 버전의 url은 /api/v2/flavors/로 칭할 수 있는 것이다. 이렇게 구성해놓으면 API 작업시 구별도 쉽고 무엇보다도 API를 변경할 때마다 기존 이용자들은 이전 버전의 API를 호출하여 사용하므로 새버전과 이전 버전의 API가 충돌하지 않는다.

또, flavors앱과 user앱 중 user앱만 부분 업데이트를 할 경우에는 기존의 /api/v1/flavors/를 계속 사용하고 /api/v2/users/로 새로운 url을 사용할 수 있기 때문에 url을 구분하여 작업할 때 훨씬 편리하다.


5. API 중단하기

기존 API 사용자들이 있을 경우에는 사용자들에게 기존 API 중단 및 업데이트 사실을 인지할 수 있도록 충분한 시간을 줘야한다. 사용을 중지하기로 한 API라도 몇 달 간은 사용할 수 있게 해주는 것이 좋다. API를 업데이트할 경우를 대비하여 오픈소스 API이라 할 지라도 미리 사용자들의 이메일 주소를 수집해놓는 것이 좋다.

1) 사용자에게 서비스 중지 예고하기

도서에 따르면 6개월 정도의 기간이 적당하고 최소 한 달 전에 알려주는 것이 좋다고 한다. API를 사용할 수 있는 메인 사이트, 이메일, 소셜 미디어, 블로그 등으로 알려주는 것이 좋다. 알림을 많이 보내서 일어날 일에 대해 걱정이 된다면 중지 사실을 모르고 일어날 문제들보다는 영향이 미미하므로 최대한 알림을 많이 보내주는 것이 좋다.


2) 410 상태코드 뷰로 API 교체하기

앞에서 기억해야 할 HTTP 상태코드로 410 GONE을 소개했다. 최종적으로 API가 중지되었을 때 간단하게 410 코드를 사용한 뷰를 이전 버전의 url에 연결해준다. 뷰에는 새로운 API에 대한 정보 및 문서로의 링크를 알려주도록 작성하면 된다.


7. API 접속 제한

접속 제한이란 한 명의 사용자가 주어진 시간에 얼마 이상의 요청을 보낼 때 이를 제어하는 것을 말한다. REST 프레임워크는 반드시 API 접속 제한 기능을 제공하는 것이 좋다. API를 유료로 서비스하는 경우에는 요청에 제한을 둠으로서 가격 정책을 세울 수도 있을 것이다.

접속 제한은 웹서버에서 처리할 수도…

nginxapache의 접속 제한을 이용하여 API 사용을 제어할 수 있다. 하지만 파이썬 코드로부터 얻을 수 있는 기능적인 여러 면을 잃어버린다. 해당 부분은 좀 더 공부를 한 후 설명을 보충하도록 할 예정이다.


8. 내가 만든 API를 어떻게 알릴까?

1. API 문서 활용

자신이 만든 API를 다른 사용자가 사용할 수 있도록 하려면 API에 대한 자세한 설명 및 사용방법을 담은 문서 제작은 필수다. 개인적으로는 Gitbook을 사용했는데 가끔씩 오류가 발생해 사용이 불편하다는 단점이 있었다. 이외에도 django-rest-framework나 마크다운으로 제공해도 된다.


클라이언트 SDK 제공하기

문서 작성이 완료되었다면 이제는 API를 좀더 널리 알리기 위해 여러 언어를 지원하는 SDK(software development kit)을 사용할 수 있다. 도서에 따르면 다음의 언어는 필수적으로 지원하는 것이 좋다고 한다.

  • 파이썬
  • 자바스크립트
  • 루비
  • PHP
  • 고(Go)
  • 자바

SDK 라이브러리를 이용하여 데모 프로젝트를 구현해보면 사용자가 실제로 API를 어떻게 경험하는지 알 수 있게 된다. (개인적으로는 클라이언트 SDK 만들기에 대한 공부를 해봐야겠다.)



Julia Hwang

디발자를 꿈꾸는 웹개발자의 블로그입니다.