사용자 중심 API 디자인

API

Application Programming Interface

서로 다른 소프트웨어 시스템 사이에서 통신 가능

• 사용자 중심 API는 직관적이고, 사용하기 쉽고, 개발자 경험을 염두에 두고 설계된 API

• 명확하고 일관성 있는 명명 규칙, 충분한 문서, 에러 핸들링 같은 측면의 고려를 포함

• API design

• Designing for humans: better practices for creating user-centric API experiences

• Designing Good API Experiences

• RESTful 웹 API 디자인 패턴

• Best Practices in API Design

일관성

• API가 다양한 컴포넌트에서 일관성을 유지하면 개발자의 인지부하를 줄인다.

• API를 보다 쉽게 이해하고 사용할 수 있음

• 일관성이 반드시 필요한 세 가지 영역

  • 명명 규칙

  • 리소스 구조

  • 응답 형식

명명 규칙

명확하고 일관성 있는 명명 규칙

• 일관성있고 직관적인 이름은 API 스스로가 설명하게 함으로써 보다 쉽게 이해하고 오해나 에러 가능성을 최소화

• 리소스 혹은 액션을 정확하게 설명하는 이름을 선택

• 소문자와 하이픈만 사용하여 가독성 높히기

• 리소스 이름에는 명사를 사용하여 리소스는 액션이 아닌 사물임을 명확하게 인지하도록 함

• CRUD 조작에 맞지 않는 액션에 대해서는 동사 사용

  • 표준 CRUD(생성, 조회, 업데이트, 삭제) 조작과 다른 특별한 액션임을 구분하는데 도움을 줌

  • /orders/{orderId}/cancel, /users/{userId}/reset-password

• 복수를 일관성 있게 표현

  • 리소스 이름을 표현할 때 단수 혹은 복수를 API 전체에서 일관성을 유지하기

  • 개발자들에게 서로 다른 리소스들과 상호작용하는 방법을 예상하는데 도움을 줌

리소스 구조

리소스 구조는 일관성을 통해 사용성을 크게 향상시킬 수 있는 영역

• API는 리소스를 논리적이고 직관적인 방법으로 조직

• 서로 다른 엔티티 사이의 관계와 API를 탐색하는 방법을 쉽게 이해하도록 도움

• 계층을 사용해 관계를 나타내기

  • 중첩된 리소스는 소속 혹은 조합을 나타냄

  • customers/{customerId}/addresses, orders/{orderId}/items

• URL을 가능한 짧게 유지함으로써 명확성 유지

  • 중첩은 유용하지만 너무 긴 URL은 피하기

• 필터링, 정렬, 페이징을 위해 매개변수 사용

  • base URL을 명확하게 유지 가능

  • 유연한 질의 가능케함

• 유사한 리소스에 대해 일관성 있는 패턴 사용

  • 두 리소스가 유사한 구조를 갖는다면 표현하는 방식에도 일관성을 유지시키기

  • /users/{userId}/profile, /companies/{companyId}/profile

응답 형식

일관성 있는 응답 형식을 제공함으로써 개발자들이 API를 통해 무엇을 기대할 수 있는지 보장

• 일관성 있는 구조를 따르면, 사용자들이 훨씬 쉽게 API가 반환하는 데이터를 파싱하고 다룰 수 있음

• 성공과 에러 응답에 대해 유사한 형식을 유지하기

// success
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "jtw"
  }
}

// error
{
  "status": "error",
  "data": {
    "message": "user not found",
    "code": "NOT_FOUND"
  }
}

• 여러 리소스가 유사한 속성을 갖는다면 같은 속성 이름 사용

  • createdAt, updatedAt 등

• 일관성 있는 날짜와 시간 형식을 사용

  • ISO 8601 같은 표준 형식을 준수
• 일관성 있는 메타데이터를 제공

  • 페이지네이션, 혹은 요청 식별자 같은 메타데이터를 모든 목록 응답에 일관성있게 포함

에러 핸들링

잘 디자인된 에러 응답은 개발자로 하여금 빠르게 이슈를 식별하고 해결하도록 도와줌

적절한 HTTP 상태 코드 사용하기

• 상태 코드는 요청 결과에 대한 표준화된 방법을 제공함

• 2xx는 요청성공, 4xx는 클라이언트 에러, 5xx는 서버 에러

상세 에러 메시지 제공

• 개발자들이 무엇이 잘못되었는지 어떻게 수정해야하는지 이해할 수 있도록 충분한 콘텍스트 제공하기

• 민감한 정보들이 노출되지 않도록 주의

일관성 있는 에러 메시지 구조 사용

• 일관성 있는 형태를 준수

• 프로그래밍적으로 에러를 쉽게 파싱하고 다룰 수 있어야함

{
  "status": "error",
  "message": "string",
  "code": "string",
  "details": "string",
  "requestId": "string"
}

고유한 에러 코드 포함

• 서로 다른 타입의 에러에 대해 고유 에러 코드를 할당

• 이를 통해 특정한 에러 시나리오를 쉽게 식별하고 처리 가능

검증 에러 처리

• 여러 필드를 포함한 요청에 대해서는 각 필드마다 개별적으로 전달하지 말고 모든 검증 에러를 한번에 전달

• 개발자들의 시간을 아껴주고 불필요한 API 호출을 줄이는데 도움됨

{
  "status": "error",
  "message": "validation failed",
  "code": "VALIDATION_ERROR",
  "errors" [{
    "field": "email",
    "message": "invalid email format"
   },
   {
     "field": "password",
     "message": "password must be ...",  
    }]
}

디버깅을 위해 에러 기록하기

• 디버깅을 위해 서버사이드에 상세한 에러 정보를 기록함을 보장하는것도 중요

• API 사용자에게 민감한 정보를 노출하지 않고 보다 효과적으로 이슈를 조사하고 해결 가능해짐

• 내부 로그에 스택 추적, 요청 매개변수, 시스템 상태 등을 포함 가능하지만 비밀번호나 API 키 같은 데이터는 기록 ❌

문서화

잘 구조화된 문서는 사용자 중심 API를 만드는데 필수적

• 학습 곡선을 상당히 줄이고

• 지원 요청을 최소화

명확한 개요 만들기

• API에 대한 고수준의 개요에서 시작하라

• API의 목적, 주요 기능, 인증 메서드, 기본 URL, 버전 관리 정보, 일반적인 유스케이스 혹은 예상 시나리오

상세한 엔드포인트 문서

• 각 엔드포인트에 관해 총체적인 정보 제공

• HTTP 메서드, 전체 URL, 엔드포인트 목적 설명, 요청 매개변수, 응답 형식 및 가능한 상태 코드

• 요청과 응답을 포함해 해당 엔드포인트가 실제로 동작하는 방식을 포함

코드 샘플 포함

• API를 사용하는 방법을 보여줘야함

인증에 관해 설명

• API 키 또는 토큰을 얻는 단계

• 요청에 인증을 포함하는 방법

• 보안 모범 사례등이 포함됨

버저닝

기존 사용자에게 혼란을 주지 않고 API의 변경과 업데이트를 관리할 수 있게 해줌

• API가 비즈니스 핵심 전략 제품 혹은 서비스 역할을 하는 경우 특히 중요해짐

• 새로운 기능과 개선사항을 도입하면서 하위 호환성을 유지할 수 있음

• 버저닝 전략으로 URL 버저닝, 쿼리 매개변수 버저닝, 헤더 버저닝이 있다.

URL 버저닝

기본 URL에 버전 번호를 포함

• GET /v1/users/123

• 가장 직관적이고 널리 사용됨

• 쉽게 이해하고 구현하기 쉬움

• 상이한 버전들을 명확하게 분리 가능

• 사소한 변경에 덜 유연함

쿼리 매개변수 버저닝

요청 URL에 API 버전을 매개변수로 지정

• GET /users/123?version=1

• 기본 URL을 깔끔하게 유지 가능

• 세세한 버전 관리 가능

• 캐싱 전략을 복잡하게 만들 수 있음,

• 주요 버전을 명확하게 구별하기 어려움

헤더 버저닝

커스텀 HTTP 헤더에 API 버전을 제공

• GET /users/123 Header: API-Version: 1

• URL을 깔끔하게 유지 가능

• 버전 관리와 리소스 식별자를 분리

• 서버에서 커스텀 헤더를 처리해야함

• 브라우저에서 테스트하기 어려울 수 있음

구식화 종료

• 새로운 버전을 도입할 때는 이전 버전의 구식화 및 궁극적인 종료에 관한 명확한 정책을 마련해야함

• 구식화 고지하기

• 타임라인 제공하기 (유예기간)

• 구식화 관련 경고 보내기 (API 응답에)

• 마이그레이션 지원 제공하기 (참고할 수 있는 문서, 도구, 지원을 제공)

보안

보안 위협과 취약점으로부터 보호 가능

• HTTPS를 사용함으로써 전송 중인 데이터를 보호하는 동시에 아래 보안 수단을 활용해 잠재적인 위협과 취약점으로부터 보호해야ㅁ

인증 허가

접근을 요청하는 엔티티가 그들이 신고한것과 일치하는지 체크

• 합법적인 사용자들만 데이터나 기능에 접근할 수 있어 API 보안 유지하는데 중요

• 요청이 인증된 뒤에는 허가를 구현해 사용자가 올바른 권한을 가지고 있음을 보장

보안 헤더

클릭재킹, 사이트 간 스크립팅, 사이트간 삽입 같은 특정 유형 공격으로부터 API를 보호

• Content-Security-Policy
• Content-Type
• Strict-Transport-Security

입력 검증과 안정성 검사

사용자 입력을 검증하고 안정성 검사를 함으로써 삽입 공격이나 악의적 활동으로부터 보호

• 입력된 데이터가 기대하는 타입, 형식, 값 범위를 갖는지 보장 가능

• 안정성 검사는 특수문자들을 제거하거나 변환해 위험한 동작을 촉발하지 않도록 막는것 포함

교차 출처 리소스 공유 CORS

웹 페이지 리소스를 자신의 출처가 아닌 다른 출처에서 요청되는 것을 허용 또는 제한하는 보안 기능

• 상이한 도메인에서 호스팅 되는 API와 상호작용하는 모던 웹 앱에서는 매우 중요

레이트 제한

API를 오용이나 잠재적인 서비스 공격에서 보호 가능

• 지정한 시간 이내에 클라이언트가 요청할 수 있는 요청 숫자를 제한하는 형태로 구현