본문 바로가기

API설계6

모바일 앱 API 오류 응답 형식을 하나로 고정해야 하는 이유와 설계 방법 (Laravel 예시) 웹과 모바일 앱 API를 같이 개발하고 운영하다 보면, 성공 응답은 data, meta, pagination 같은 구조를 예쁘게 잘 맞춥니다. 앱 화면에서 바로 쓰기 좋은 형태로 신경을 많이 쓰죠.그런데 오류 응답은 생각보다 뒤로 밀리기 쉽습니다. 저의 경우도 처음에는 대충 에러 메시지만 던져줬다가, 앱 쪽에서 예외 처리가 자꾸 꼬이는 문제를 겪었습니다. 어떤 API는 message로 오고, 어떤 API는 error로 오고, 서버가 터지면 HTML 오류 페이지가 날아오니 앱 인터셉터(Interceptor)에서 공통 처리를 만들기가 불가능하더군요.앱 API에서 오류 응답은 하나의 '계약'입니다. HTTP status만 맞추는 걸로 끝내면 안 되고, 앱이 화면 안내, 재로그인, 필드별 에러 표시, 재시도 같.. 2026. 5. 21.
[Next.js 전환] 기존 Backend/CMS를 Next.js로 바꿀 때 앱 API 경계 유지하는 방법 이래저래 서비스를 운영하다 보면, 기존 Laravel(PHP)로 되어 있는 백엔드나 CMS 프로젝트를 Next.js로 전환하고 싶을 때가 있습니다.저의 경우도 최근 관리자 CMS 화면을 Next.js로 바꾸고 앞단에 BFF(Backend For Frontend)를 두는 구조를 검토했었는데요. 이때 가장 헷갈리고 조심해야 하는 부분이 바로 화면과 앱 API 사이의 경계를 어디서 나눌지 정하는 일입니다.화면 바꾸는 김에 API 구조도 싹 정리하면 깔끔할 것 같지만, 실제 운영해보면 화면 전환과 앱 API 계약 변경은 완전히 다른 문제입니다. 이미 배포된 모바일 앱은 사용자들이 바로 업데이트를 안 하기 때문에, 응답 필드 하나만 잘못 바꿔도 구버전 앱에서 바로 크래시가 나거나 장애로 이어집니다.기존 앱 API.. 2026. 5. 21.
[Backend] API 캐시(Cache)와 레이트 리밋(Rate Limit) 적용할 때 놓치는 실무 운영 기준 정리 웹이든 앱이든 서버를 같이 만지며 운영하다 보면, 같은 콘텐츠를 여러 사용자가 반복해서 조회하는 상황을 자주 보게 됩니다. 공지사항, 배너, 카테고리 목록 같은 공개 데이터는 매번 DB에서 무겁게 긁어올 필요가 없죠. 이럴 때 캐시를 적절히 붙여주면 응답 속도도 빨라지고 DB 부하도 크게 줄일 수 있습니다.반대로 시스템을 보호하는 고민도 해야 합니다. 봇이 들어와서 목록 API를 과도하게 긁어가거나, 특정 검색 API를 짧은 시간에 마구 호출하면 서버 자원이 금방 바닥납니다. 이때는 Rate Limit(요청 제한)을 걸어서 필터링을 해줘야 합니다.처음에는 '캐시는 빠르게 만드는 기능, 레이트 리밋은 과도한 요청을 막는 기능' 정도로 쉽게 생각하기 쉬운데요. 실무에서 기준 없이 대충 붙였다가는 오히려 데이.. 2026. 5. 21.
[Backend] 앱 API 목록 조회 설계 기준 정리 (Pagination, Filter, Sort Allowlist) 앱 Backend API를 만들 때 목록 조회는 정말 숨 쉬듯 만드는 기능입니다. 공지사항, 게시글, 배너, 관광지 목록 등 화면에 뿌려주는 데이터의 90%는 목록이니까요.처음에는 그냥 page, keyword 정도만 대충 받아서 넘겨도 잘 돌아가는 것처럼 보입니다. 하지만 서비스가 조금만 커지면 정렬 기준이 추가되고, 카테고리나 지역 필터가 붙고, 관리자 상태값 처리까지 뒤엉키면서 API마다 파라미터 이름과 응답 구조가 제각각이 되기 일쑤입니다.저의 경우에도 혼자서 서버와 앱을 같이 만지다 보니, 초기에 기준을 안 잡아두면 나중에 프론트엔드 코드 짤 때 공통 처리가 안 돼서 고생하곤 했습니다. 자꾸 까먹고 놓치는 부분이 많아서 실무에 바로 적용할 수 있도록 기준을 정리해 둡니다.1. 내가 겪었던 문제들.. 2026. 5. 20.
[API 개발] DB Model을 그대로 반환하면 안 되는 이유 (DTO와 Serializer로 응답 계약 고정하기) 웹이랑 모바일 앱, 서버까지 이래저래 같이 잡고 운영하다 보면 API 응답 구조 때문에 꼭 한 번씩 골치 아픈 일이 생깁니다.처음 API 만들 때는 그냥 DB에서 조회한 모델(Model) 객체를 그대로 JSON으로 던지는 게 가장 편합니다. 코드 한두 줄이면 끝나고 개발 속도도 엄청 빠르니까요. 저도 예전에는 초기 빌드할 때 종종 그렇게 고집을 부렸습니다.하지만 모바일 앱과 연동되는 API라면 이 방식은 머지않아 시한폭탄이 됩니다. DB 컬럼 하나 바꿨다고 이미 배포된 앱이 죽어버리거나, 관리자용 내부 메모 같은 민감한 필드가 앱 패킷에 그대로 노출되는 사고가 터지기 때문입니다.자꾸 까먹기도 하고, 다음 프로젝트에서 실수하지 않기 위해 DTO와 Serializer를 활용해 API 응답 형식을 안전하게 고.. 2026. 5. 20.
[백엔드 설계] 관리자 CMS와 모바일 앱 API 코드를 처음부터 분리해야 하는 이유 웹이랑 앱, 서버를 같이 만지며 운영하다 보면 꼭 마주치는 상황이 있습니다. 바로 공지사항, 관광지 정보, 배너, 카테고리 같은 데이터를 관리자 CMS에서 등록하고, 모바일 앱에서 API로 조회해서 보여주는 구조입니다.처음에는 "어차피 똑같은 DB 데이터 긁어다 쓰는 건데 대충 같이 쓰면 안 되나?" 하고 Controller나 Query를 같이 재사용하고 싶어집니다. 코드가 줄어드니까 처음엔 속도가 빠른 것처럼 느껴지거든요. 하지만 이거 귀찮다고 대충 섞어 쓰면 나중에 운영 중에 무조건 사고가 터지거나 고치느라 고생하게 됩니다.관리자는 수정, 삭제, 내부 메모나 검수 상태 확인이 필요하지만, 앱은 외부 사용자가 보는 거라 공개 가능한 데이터만 안정적인 형태로 받아야 하기 때문입니다. 저도 자꾸 까먹고 실.. 2026. 5. 20.

티스토리툴바