본문 바로가기

API설계6

[Backend/API] Backend 앱 API에서 오류 응답 형식을 고정하는 기준 API를 만들 때 성공 응답은 비교적 신경을 많이 쓰게 됩니다. data, meta, DTO, pagination 같은 구조를 맞추고, 앱 화면에서 사용하기 좋은 형태로 응답을 정리하죠.그런데 오류 응답은 생각보다 뒤로 밀리기 쉽습니다. 인증 실패, 권한 부족, 유효성 검증 실패, rate limit, 서버 오류가 모두 다른 형식으로 반환되면 모바일 앱은 오류 처리를 안정적으로 만들기 어렵습니다.앱 API에서는 오류 응답도 하나의 계약입니다. HTTP status만 맞추는 것으로 끝나지 않고, 앱이 화면 안내, 재로그인, 입력값 표시, 재시도, 고객센터 문의 같은 흐름을 만들 수 있도록 JSON 구조를 고정해야 합니다.처음에는 오류 상황마다 필요한 메시지만 내려주면 충분해 보일 수 있습니다. 하지만 실제.. 2026. 5. 21.
[Backend/CMS] CMS를 Next.js로 전환할 때 API 경계를 유지하는 기준 기존 Backend/CMS 프로젝트를 Next.js로 전환하려고 할 때 가장 헷갈리는 부분은 화면과 API 사이의 경계를 어디에서 나눌지 정하는 일입니다. 관리자 CMS 화면을 Next.js로 바꾸거나, 앱 API 앞단에 BFF를 두는 구조를 검토하다 보면 기존 Laravel/PHP API, 관리자 route, 앱 API 응답 계약이 한꺼번에 흔들릴 수 있습니다.이때 중요한 기준은 기존 앱 API 계약을 쉽게 깨지 않는 것입니다. 모바일 앱은 이미 배포된 버전이 있을 수 있고, 모든 사용자가 동시에 업데이트될 수 있는 것도 아닙니다. 그래서 CMS 화면을 Next.js로 바꾸더라도 앱 API의 DTO, 인증, 캐시, versioning 경계는 분리해서 유지해야 합니다.처음에는 Next.js로 화면을 옮기.. 2026. 5. 21.
[Backend/API] 캐시와 rate limit을 설계하는 기준 Backend 앱 API를 운영하다 보면 같은 콘텐츠를 여러 사용자가 반복해서 조회하는 경우가 많습니다. 공지사항, 배너, 카테고리, 관광지 목록처럼 공개 데이터는 매번 DB에서 조회하지 않아도 되는 경우가 많죠. 이럴 때 캐시를 사용하면 응답 속도를 개선하고 DB 부하를 줄일 수 있습니다.반대로 요청이 너무 많이 들어오는 상황도 생각해야 합니다. 검색 API를 짧은 시간에 반복 호출하거나, 봇이 목록 API를 과도하게 요청하면 서버 자원을 빠르게 소모할 수 있습니다. 이때 rate limit을 적용하면 일정 기준을 넘는 요청을 제한할 수 있습니다.처음에는 캐시는 성능을 빠르게 만드는 기능, rate limit은 요청을 막는 기능 정도로만 생각하기 쉽습니다. 하지만 실제로 정리해보면 캐시와 rate li.. 2026. 5. 21.
[Backend/API] 목록 조회 pagination, search, filter를 설계하는 기준 Backend 앱 API에서 목록 조회는 거의 모든 서비스에 들어가는 기본 기능입니다. 공지 목록, 관광지 목록, 게시글 목록, 배너 목록처럼 앱 화면은 대부분 목록 데이터를 받아서 렌더링합니다. 그런데 pagination, search, filter, sort 기준을 처음부터 정하지 않으면 API마다 파라미터 이름과 응답 구조가 달라지기 쉽습니다.처음에는 page, keyword 정도만 받아도 충분해 보입니다. 하지만 앱이 커지면 정렬 기준, 카테고리 필터, 지역 필터, 공개 상태, hasNext, limit 제한, 빈 결과 처리까지 함께 봐야 합니다.특히 관리자 CMS 목록 조회와 앱 API 목록 조회는 목적이 다릅니다. 같은 query를 그대로 쓰면 내부 필드나 DB 컬럼 기준이 앱에 노출될 수 있.. 2026. 5. 20.
[Backend/API] DTO와 serializer로 응답 형식을 고정하는 방법 Backend 앱 API에서 DTO와 serializer로 응답 형식을 고정하는 방법Backend 앱 API를 만들 때 가장 편한 방식은 DB model을 그대로 JSON으로 반환하는 것입니다. 이게 처음에는 빠르고 단순해 보일지 몰라도 모바일 앱과 연결되는 API라면 이 방식은 금방 문제가 될 수 있습니다. DB 컬럼이 바뀌면 앱 응답도 같이 바뀌고, 내부 관리 필드가 앱에 노출될 위험도 커지기 때문입니다.이럴 때 DTO와 serializer를 사용하면 API 응답 형식을 고정할 수 있습니다. DTO는 앱에 내려줄 데이터 구조를 정의하고, serializer는 DB model이나 내부 객체를 DTO 형태의 배열 또는 JSON으로 바꾸는 역할을 합니다. 이렇게 분리하면 DB 구조와 앱 응답 계약을 나눌 .. 2026. 5. 20.
[Backend/CMS] 프로젝트에서 관리자 화면과 앱 API를 분리하는 기준 Backend/CMS 프로젝트를 만들다 보면 관리자 화면과 모바일 앱 API가 같은 데이터를 다루는 경우가 많습니다. 예를 들어 공지사항, 관광지 정보, 배너, 카테고리, 사용자 문의 같은 데이터는 관리자 CMS에서 등록하고 앱에서는 API로 조회하게 됩니다.처음에는 같은 controller나 같은 query를 재사용하고 싶어질 수 있습니다. 그렇지만 관리자 화면과 앱 API는 목적이 다릅니다. 관리자는 수정, 삭제, 내부 상태 확인이 필요하고, 앱은 공개 가능한 데이터만 안정적인 응답 형태로 받아야 합니다.이 차이를 분리하지 않으면 내부 필드가 앱에 노출되거나, 관리자 인증 기준이 API와 섞이는 문제가 생길 수 있습니다. 처음에는 같은 코드를 재사용하는 쪽이 빠르게 느껴지지만, 실제로 정리해보면 관리.. 2026. 5. 20.

티스토리툴바