🌿 중급 백엔드
API 엔드포인트는 어떻게 설계하나요?
쉽게 이해하기
도서관에서 책을 찾을 때 '1층-문학-한국소설-김OO' 같은 체계적인 분류를 따르듯이, API 엔드포인트도 '/users/123/posts/456' 같은 명확한 규칙을 따라 설계해요. 누가 봐도 '유저 123번의 게시글 456번'이라는 걸 알 수 있죠.
핵심 정리
API 엔드포인트 설계 원칙을 알면 직관적이고 사용하기 쉬운 API를 만들 수 있어요.
자세히 알아보기
API 엔드포인트를 설계할 때는 몇 가지 중요한 원칙이 있어요. 첫째, 명사를 사용하고 복수형으로 표현하는 게 좋아요. '/getUsers' 대신 '/users'처럼요. 동사는 HTTP 메서드(GET, POST 등)로 표현하니까요.
둘째, 계층 구조를 잘 표현해야 해요. '/users/123/orders'는 '123번 유저의 주문 목록'이라는 의미를 직관적으로 전달하죠. 이렇게 하면 개발자들이 API 문서를 보지 않아도 엔드포인트의 의미를 쉽게 이해할 수 있어요.
셋째, 버전 관리를 고려해야 해요. '/v1/users' 같은 식으로 버전을 명시하면 나중에 API를 업데이트할 때 기존 사용자에게 영향을 주지 않을 수 있어요. 실무에서는 '/api/v1/products'처럼 api 접두사와 버전을 함께 쓰는 경우가 많아요.
넷째, 필터링이나 정렬은 쿼리 파라미터로 처리해요. '/products?category=electronics&sort=price' 같은 식이죠. 이렇게 하면 엔드포인트가 너무 복잡해지지 않고 깔끔하게 유지돼요. 좋은 API 설계는 개발자 경험을 크게 향상시켜서 협업할 때나 나중에 유지보수할 때 훨씬 편해요.