내부 구현 대신 약속된 접점
프로그램은 API가 정한 호출 방법에 따라 다른 기능을 이용한다. 내부에서 어떤 자료 구조와 알고리즘을 사용하는지 모두 알지 않아도 동작할 수 있도록 경계를 만든다.
호출 이름만 공개하면 충분한 것은 아니다. 어떤 입력을 받는지, 실패를 어떻게 나타내는지, 상태를 바꾸는지와 자원 수명 등을 명확히 해야 사용할 수 있는 계약이 된다.
웹 API는 한 종류다
웹 API는 HTTP 등의 요청과 응답으로 기능과 데이터를 제공한다. 그러나 API 전체가 URL 목록이나 JSON 통신만을 뜻하는 것은 아니다. 같은 프로세스 안의 라이브러리도 API를 갖는다.
데이터 형식과 통신 방식, 응용의 동작 규칙은 서로 다른 층위다. JSON을 사용한다는 사실만으로 REST 같은 설계 원칙을 모두 만족한다고 할 수는 없다.
인증과 권한
API 키나 로그인 토큰은 요청 주체를 확인하는 데 사용될 수 있다. 주체가 확인되더라도 모든 기능과 데이터에 접근할 권한을 주어서는 안 된다.
요청마다 필요한 권한과 대상 자원의 범위를 검사해야 한다. 클라이언트 화면에서 기능을 감추는 방식은 서버의 접근 제어를 대신하지 못한다.
호환성과 운영
사용 중인 API의 필드를 없애거나 의미를 바꾸면 다른 프로그램이 실패할 수 있다. 버전과 지원 기간, 변화의 범위를 명확히 안내하는 것이 호환성 관리다.
요청 제한과 지연, 재시도 및 중복 처리도 실제 이용에 영향을 준다. 같은 요청을 다시 보냈을 때 결과가 어떻게 달라지는지 정의해야 안정적인 연동을 만들 수 있다.