급여 시스템에서 API를 설계할 때, JSON 형식으로 데이터를 주고받는다. 프론트엔드에서 급여 정보를 조회하거나, 외부 시스템과 연동할 때 JSON 구조를 잘 설계해야 한다. JSON 포매터로 데이터 구조를 정리하면서 API 설계 원칙을 알아본다.
급여 조회 API 응답 구조
직원이 자신의 급여를 조회할 때 반환하는 JSON 예시다.
{ "employeeId": "EMP001", "period": "2026-02", "grossSalary": 5000000, "deductions": { "nationalPension": 225000, "healthInsurance": 177250, "longTermCare": 22954, "employmentInsurance": 45000, "incomeTax": 150000, "localIncomeTax": 15000 }, "netSalary": 4364796, "paymentDate": "2026-02-25" }
gooale.kr/json-formatter에 붙여넣으면 보기 좋게 정렬된다.
API 버전 관리
급여 시스템 API는 한 번 배포하면 바꾸기 어렵다. 클라이언트 앱이 이미 배포되어 있기 때문이다. 그래서 버전 관리가 중요하다.
/api/v1/salary/EMP001 /api/v2/salary/EMP001
새 필드를 추가하거나 구조를 바꿀 때 v2를 만들고, v1은 당분간 유지한다.
에러 응답 설계
성공뿐 아니라 에러 응답도 일관된 형식이 필요하다.
{ "error": true, "code": "SALARY_NOT_FOUND", "message": "해당 월의 급여 정보가 없습니다.", "details": { "period": "2026-02" } }
에러 코드를 정의해두면 클라이언트에서 적절한 처리를 할 수 있다.
민감 정보 처리
급여 데이터는 민감 정보다. API 응답에 불필요한 정보를 포함하지 않도록 주의한다. 예를 들어 주민등록번호 전체를 반환하면 안 되고, 뒷자리는 마스킹한다. JSON 포매터로 응답을 검토할 때 민감 정보 노출 여부도 확인한다.
페이지네이션
급여 이력을 조회할 때 수년치 데이터가 있을 수 있다. 한 번에 다 반환하지 말고 페이지네이션을 적용한다.
{ "data": [...], "pagination": { "page": 1, "pageSize": 12, "totalPages": 5, "totalCount": 60 } }
캐싱 전략
급여 데이터는 월 1회 확정되면 바뀌지 않는다. 캐싱을 적용하면 서버 부하를 줄일 수 있다. Cache-Control 헤더를 설정하거나 Redis에 캐싱한다.
결론
API 응답 설계는 사용성, 보안, 성능을 모두 고려해야 한다. JSON 구조를 점검할 때 온라인 JSON 포매터를 활용하면 편리하다.