API는 화면이나 다른 시스템이 서버에 요청하고 결과를 받는 접점입니다. API 설계에서는 요청 항목, 응답 형식과 권한, 실패했을 때의 처리를 정합니다.
예약 화면
서버
조회 요청
날짜선택한 날짜 서비스 종류선택한 서비스
예약 화면이 서버에 선택한 날짜와 서비스 종류를 보내 예약 가능한 시간을 조회합니다. 필요한 입력과 조회 권한을 함께 확인합니다.
결과 응답
가능한 시간조회 결과 목록
서버는 조회 결과를 정한 형식으로 반환합니다. 화면은 가능한 시간을 표시하고 결과가 없거나 요청이 실패한 경우를 구분해 안내합니다.
화면은 정해진 접점을 통해 서버의 기능을 사용합니다. 화면의 표시 방식과 서버의 자료 처리 방식을 분리하고, 양쪽이 공유하는 요청, 응답 규칙을 문서로 정합니다.
- 부탁하는 말
- 요청 항목
- 주고받는 양식
- 전달 형식
- 돌아오는 답
- 처리 결과와 오류
화면과 서버의 역할 구분
화면표시, 입력, 최신 상태 확인
서버상태, 권한, 업무 규칙, 자료
여러 사용자가 같은 예약과 업무 자료를 이용할 때는 서버에서 상태와 권한을 관리합니다. 화면은 필요한 시점에 최신 상태를 확인하고 변경 충돌을 처리해야 합니다.
개발비에는 화면 표시와 입력 처리, 서버의 업무 규칙과 자료 처리 등이 포함됩니다. 견적에서 항목이 나뉘면 각 작업의 범위와 연동, 시험의 포함 여부를 확인합니다.
요청 상태와 사용자 안내
사용자에게 직접 보이는 상태는 요청 중, 실패와 중복 시도 등으로 구분합니다. 화면과 서버의 대응을 함께 설계합니다.
요청 중처리 중임을 표시하고 오래 걸릴 때의 안내와 제한 시간을 정합니다.
요청 실패통신 실패와 처리 실패를 구분하고 재시도, 문의 방법을 제공합니다.
중복 요청재클릭과 통신 재시도로 같은 업무가 반복 처리되지 않도록 설계합니다.
예약과 결제는 버튼의 재클릭뿐 아니라 통신 재시도로도 중복 요청이 발생할 수 있습니다. 화면의 입력 제한과 서버의 중복 처리 방지를 함께 확인하고 결과 조회 방법을 마련합니다.
응답 지연의 원인과 측정
응답 지연은 네트워크, 요청 방식과 서버, 자료 처리 등 여러 원인으로 발생합니다. 화면별 측정 결과를 기준으로 원인을 조사합니다.
여러 요청의 순차 처리
반복 조회와 순차 요청이 지연을 늘리는지 측정합니다. 요청 통합과 병행 처리의 효과와 영향을 검토합니다.
개별 요청의 처리 지연
서버 처리, 외부 연동과 자료 조회 시간을 나눠 확인합니다. 자료 관계와 검색 방식도 조사 대상입니다.
요청 횟수와 각 요청의 처리 시간, 화면 표시 시간을 구분해 확인합니다. 관찰한 현상과 조사 결과, 개선 후의 측정 기준을 기록합니다.
외부 서비스의 연동 조건
결제, 문자와 지도 등은 외부 서비스와 연동할 수 있습니다. 외부 서비스의 이용 조건과 장애가 업무에 미치는 영향을 검토합니다.
외부 서비스의 장애와 변경 대응
- 제한 시간
- 재시도
- 대체 처리
- 안내
외부 서비스의 지연이나 점검, 규격 변경에 대비해 위 순서의 처리를 정합니다. 장애 원인과 계약 범위를 확인하기 전에 책임을 단정하지 않습니다.
가입, 심사와 계정 준비, 이용료와 사용량 제한, 장애 시 처리 방법을 확인합니다. 준비 기간과 담당자, 시험 환경을 개발 일정에 반영합니다.
공통 규격과 병행 작업
화면 담당가상 응답으로 작업
합의한 요청, 응답 형식
서버 담당규격대로 구현
실제 연동 시험과 변경 관리
화면과 서버 담당자가 요청, 응답 형식을 합의하면 가상 응답으로 일부 작업을 병행할 수 있습니다. 실제 연동 시험과 변경 관리는 별도로 필요합니다.
설계 문서에는 입력, 출력과 오류, 권한, 버전을 기록합니다. 사업 담당자는 업무 조건과 사용자에게 보이는 결과를 검토하고 개발 담당자는 기술 규격과 시험을 담당합니다.
인증, 권한, 기록과 버전 관리
인증과 권한, 요청량 제한과 처리 기록 등 화면에 직접 드러나지 않는 기능도 필요합니다. 적용 범위와 운영 책임을 견적과 설계에서 확인합니다.
요청 머리글에 담기는 확인
- 인증과 권한
- 요청자의 신원과 해당 자료에 대한 조회, 처리 권한을 확인합니다.
- 요청량 관리
- 과도한 요청과 서비스 남용에 대응할 제한 기준을 정합니다.
- 처리 기록
- 오류 조사에 필요한 정보를 남기되 개인정보와 비밀 정보의 기록 범위를 제한합니다. 운영 오류를 접수하고 재현하는 데 활용할 수 있습니다.
- 버전 호환
- 기존 앱의 지원 범위와 변경, 종료 절차를 관리합니다.
앱의 여러 버전이 동시에 사용될 수 있으므로 지원할 버전과 종료 기준을 정합니다. 변경된 서버 기능이 기존 앱에 미치는 영향과 업데이트 안내를 시험합니다.
화면과 처리 결과의 검수
검수에서는 정상 결과와 함께 대기, 통신 실패와 중복 요청을 확인합니다. 사용자에게 필요한 안내와 재처리 방법이 제공되는지 점검합니다.
| 상태 | 확인할 것 |
|---|---|
| 대기 상태 | 진행 상태와 제한 시간 이후의 안내를 확인합니다. 필요하면 취소와 결과 조회 방법을 제공합니다. |
| 실패 상태 | 사용자가 이해할 수 있는 원인과 다음 행동을 안내합니다. 재시도해도 되는지와 문의 방법을 구분합니다. |
| 중복 요청의 결과 | 버튼을 반복 누르거나 응답이 끊긴 뒤 재시도해도 같은 예약, 결제가 중복 처리되지 않는지 시험합니다. |
기관, 기업의 기존 시스템 연동
기관, 기업의 기존 시스템과 연동할 때는 제공 가능한 자료와 기능, 권한과 승인 절차를 확인합니다. 기존 운영 업체와 담당 부서의 협의 범위를 정합니다.
연동 가능 여부와 비용, 자료 제공 조건과 시험 일정을 사업 초기에 확인합니다. 미확인 항목은 가정과 위험으로 표시하고 대안을 검토합니다. 관련 조건은 의뢰 전 요청서에 반영합니다.
API 설계의 확인 항목
요청, 응답과 권한, 실패, 중복 처리와 버전 조건을 정합니다. 화면의 안내와 실제 처리 결과를 함께 시험하고 외부 연동의 준비 조건을 확인합니다.
자주 묻는 질문
01API 설계에서는 무엇을 정합니까
요청 항목, 응답 형식과 권한, 실패했을 때의 처리를 정합니다. 화면과 서버가 공유하는 요청과 응답 규칙은 문서로 정합니다.
02예약이나 결제가 중복 처리되지 않도록 하려면 어떻게 합니까
버튼의 재클릭뿐 아니라 통신 재시도로도 중복 요청이 발생할 수 있습니다. 화면의 입력 제한과 서버의 중복 처리 방지를 함께 확인하고 결과 조회 방법을 마련합니다.
03화면 응답이 느릴 때 원인은 어떻게 찾습니까
요청 횟수와 각 요청의 처리 시간, 화면 표시 시간을 구분해 측정합니다. 서버 처리, 외부 연동과 자료 조회 시간을 나눠 확인하고 개선 후의 측정 기준을 기록합니다.
04결제나 문자 같은 외부 서비스를 연동할 때 무엇을 확인합니까
가입과 심사, 계정 준비, 이용료와 사용량 제한, 장애 시 처리 방법을 확인합니다. 외부 서비스의 지연이나 규격 변경에 대비해 제한 시간과 재시도, 대체 처리와 안내를 정합니다.
05검수 때는 정상 결과 외에 무엇을 시험합니까
대기 상태, 통신 실패와 중복 요청을 함께 시험합니다. 사용자에게 필요한 안내와 재처리 방법이 제공되는지, 반복 요청에도 같은 예약과 결제가 중복 처리되지 않는지 점검합니다.