[TIL]20240718 /api를 두는 이유

과제코드리뷰를 받으면서 /api를 두는 이유에 대해서 기술매니저님이 질문하셨는데 당당히 모른다고 했다. 진짜 잘 몰라서애매하게도 대답을 못 하던 그 상황이 다시 오는게 싫어서 오늘 개발일지 주제로 정했다!

웹 애플리케이션에서 RESTful API를 설계할 때 URI에 /api를 두는 이유와 그 중요성에 대해 공부했다. RESTful 원칙에 따라 API를 설계하는 과정에서 /api 경로를 사용하는 것은 단순한 관습 이상의 의미를 가지고, 다양한 측면에서 고려할 가치가 있다! 

▶ URI(Uniform Resource Identifier)의 역할

URI(Uniform Resource Identifier)는 웹 상에서 자원을 식별하는 표준화된 주소 형식이다. URI는 RESTful API의 기본 요소로, 특정 자원을 고유하게 식별하고 해당 자원에 접근할 수 있는 경로를 제공한다. 예를 들어, /users/1이라는 URI는 ID가 1인 사용자를 식별하고, /users는 전체 사용자 목록을 나타낼 수 있다.

URI는 자원의 계층 구조를 표현하고, 클라이언트가 서버에서 자원에 접근하는 방식을 직관적으로 이해할 수 있도록 설계되어야 한다. 이때, URI에 /api를 추가하는 것은 RESTful 원칙을 준수하면서 API를 더 명확하고 관리하기 쉽게 만들어준다.

▶ /api를 사용하는 이유

URI에 /api를 포함하는 이유는 다음과 같은 장점과 중요성을 가진다:

 

▷ 클라이언트와 서버 간의 명확한 API 경로 구분:

URI에 /api를 사용함으로써 웹 애플리케이션의 클라이언트 측 경로와 서버 측 API 경로를 명확히 구분할 수 있다. 예를 들어, 사용자가 브라우저에서 접근하는 웹 페이지의 URI가 /home인 경우, API 경로는 /api/home으로 명확히 구분할 수 있다. 이는 클라이언트가 API와 웹 페이지의 엔드포인트를 혼동하지 않도록 도와준다.

 

▷  API 버전 관리의 용이성:

URI에 /api를 추가하면, 버전 관리를 쉽게 적용할 수 있다. 예를 들어, /api/v1/users와 /api/v2/users와 같은 URI를 사용하여 동일한 자원에 대해 서로 다른 버전을 제공할 수 있다. 이를 통해 클라이언트는 특정 버전의 API를 명시적으로 요청할 수 있고, 서버는 하위 호환성을 유지하면서 새로운 기능을 점진적으로 추가할 수 있다.

 

▷ 보안 및 접근 제어 정책의 명확성:

/api 경로를 사용하면 서버 측에서 클라이언트와 API 요청을 쉽게 구분하여 보안 정책을 적용할 수 있다. 예를 들어, /api로 시작하는 모든 요청에 대해 특정 인증 및 권한 부여 정책을 적용하거나, 특정 CORS(Cross-Origin Resource Sharing) 규칙을 설정할 수 있다.

 

▷ 백엔드 API와 프론트엔드 라우팅의 충돌 방지:

RESTful API와 프론트엔드 애플리케이션이 동일한 도메인에서 동작할 때, /api와 같은 프리픽스를 사용하면 URL 충돌을 방지할 수 있다. 예를 들어, 프론트엔드 애플리케이션의 경로로 /dashboard가 사용될 때, API 경로 /api/dashboard는 명확히 구분된다.

 

▷ 기술 스택 변화에 대한 유연성 제공:

URI에 /api를 두면, 이후 서버의 기술 스택이 변경되거나 백엔드 서비스를 다른 서버로 분리하는 경우에도 클라이언트 쪽에서 큰 변화를 주지 않고 경로를 유지할 수 있다. 예를 들어, /api 경로 하위에 있는 모든 요청을 다른 서버로 프록시할 수 있다.

 

▷ RESTful의 명확한 표현과 개발 관습 준수:

/api는 API 경로임을 명시적으로 표현함으로써, API 소비자와 개발자 모두에게 직관적이고 명확한 인터페이스를 제공한다. 이는 RESTful 설계 원칙에 맞는 개발 관습을 따름으로써, 코드의 가독성과 유지보수성을 높인다.

 

▶ RESTful API 설계에서 /api의 사용 예시

다음은 /api 경로를 사용한 RESTful API 설계의 예시.

사용자 목록 조회	GET	/api/v1/users	모든 사용자 정보를 조회한다.
사용자 정보 조회	GET	/api/v1/users/{id}	특정 ID를 가진 사용자의 정보를 조회한다.
사용자 생성	POST	/api/v1/users	새로운 사용자를 생성한다.
사용자 정보 수정	PUT	/api/v1/users/{id}	특정 ID를 가진 사용자의 정보를 수정한다.
사용자 삭제	DELETE	/api/v1/users/{id}	특정 ID를 가진 사용자를 삭제한다.

이 예시는 /api/v1을 사용하여 API 경로임을 명확히 했고, 버전 관리(v1)를 통해 API 버전을 관리하고 있다. 이를 통해 클라이언트는 명확한 URI로 서버의 자원에 접근하고, 필요한 데이터를 효율적으로 관리할 수 있다.

 

▶ 예시 설명

위의 API 설계는 다음과 같은 RESTful의 원칙과 /api 사용의 장점을 잘 보여준다:

 

→ 자원 식별:

각 자원(사용자)은 /api/v1/users와 같은 고유한 URI로 식별된다.

→  버전 관리:

/api/v1과 같은 버전 정보가 포함된 URI를 사용하여, API의 하위 호환성을 유지하면서 새로운 기능을 쉽게 추가할 수 있다.

→   프론트엔드와 백엔드의 명확한 구분:

/api 프리픽스를 사용하여 클라이언트 측의 경로와 서버의 API 경로를 명확히 구분할 수 있다.

 

▶ /api 사용 시 주의할 점

→   명확한 URI 설계:

/api 경로를 사용하더라도 자원의 계층 구조와 의미를 명확하게 표현해야 한다. URI에 불필요한 정보가 포함되지 않도록 주의해야 한다.

→   버전 관리 전략 수립:

/api/v1과 같은 버전 관리는 유연한 API 변경을 가능하게 하지만, 모든 API 수정에 버전을 증가시키는 것은 유지보수의 어려움을 초래할 수 있다. 필요할 때만 버전을 관리하도록 해야 한다.

→  보안과 접근 제어:

/api 경로 하위의 모든 엔드포인트에 대해 일관된 보안 정책을 설정하고, 접근 제어를 명확히 해야 한다.

 

▶정리 

이번 개발일지를 통해, URI에 /api를 두는 이유와 그 중요성에 대해 조금은 이해할 수 있었다. /api는 RESTful API 설계에서 클라이언트와 서버 간의 경로를 명확히 구분하고, 버전 관리와 보안, 프론트엔드와 백엔드의 경로 충돌 방지 등 다양한 장점을 제공한다. 앞으로는 RESTful 설계 원칙을 준수하여, 명확하고 일관된 URI 설계를 통해 확장 가능하고 유지보수하기 쉽게 코드를 작성하도록 해야하는데....! 아직도 너무 어렵다ㅠㅠ