API, REST API, RESTful API 개념 정리

👉 API(Application Programming Interface)

• 정의
  • 소프트웨어 애플리케이션 간에 상호 작용을 가능하게 하는 일련의 정의, 프로토콜 및 도구들의 집합
  • 이를 통해 개발자는 한 애플리케이션에서 다른 애플리케이션의 기능이나 데이터에 액세스할 수 있음
    
    
    
    

👉 REST API(Representational State Transfer API)

• 정의
  • 웹의 장점을 최대한 활용하는 API
  • 웹 서비스를 위한 아키텍처 스타일을 기반으로 한 API
  • REST는 특정 프로토콜이나 표준이 아니라 디자인 가이드라인과 원칙의 집합
    • ⇒ REST API는 URL 설계 방식
  • REST API는 일반적으로 HTTP 프로토콜을 사용하여 CRUD(Create, Read, Update, Delete) 연산을 수행
  • 자원을 이름으로 구분해 자원의 상태를 주고받는 API 방식
• 특징
  • 주소와 메서드만 보고 요청의 내용을 파악할 수 있음
• 사용하는 방식
  • 자원(Resource) 중심 설계
    • URL에는 액션은 포함하지 않고, 자원을 표시해야 함(자원 중)
      • /question/1 ⇒ 옳은 예시
      • /show/question/1 ⇒ show라는 동사가 들어가 부적합한 예시
  • 복수 명사 사용
    • 자원의 이름은 가능한 복수형을 사용
      • /users ⇒ 옳은 예시
      • /user ⇒ 부적합
  • 액션은 HTTP 메서드로 표현
    • GET: /users (모든 사용자 조회)
    • POST: /users (사용자 추가)
    • GET: /users/123 (ID 123인 사용자 조회)
    • PUT: /users/123 (ID 123인 사용자 수정)
    • DELETE: /users/123 (ID 123인 사용자 삭제)
  • 하위 자원 표현
    • 자원 간의 관계나 계층 구조는 ‘/’를 사용하여 표현
  • Filtering, Sorting, Paging
    • 특정 조건을 사용하여 자원을 필터링하거나 정렬, 페이징을 하고 싶을 때는 쿼리 파라미터를 활용
  • 상태 코드 활용
    • HTTP 상태 코드를 사용하여 API 응답의 상태를 명확하게 전달
  • 버전 관리
    • API의 버전을 관리하려면 URL에 버전 정보를 포함시키거나 HTTP 헤더를 사용
  • 명료성 유지
    • URL은 가능한 직관적이어야 함
    • 사용자가 URL만 보고도 해당 자원의 의미를 파악할 수 있어야 함
  • 케이스 일관성
    • URL의 케이스는 일관성 있게 선택하고 사용해야 함
    • 예를 들어, kebab-case (/api/users/user-preferences), snake_case (/api/users/user_preferences), camelCase (/api/users/userPreferences) 등 중 하나를 선택하고 일관성 있게 사용
      
      
      
      

👉 RESTful API

• 정의
  • REST 아키텍처 원칙과 가이드라인을 엄격하게 따르는 API를 의미
  • RESTful은 'REST 원칙을 완전히 따르는'이라는 의미
    
    
    
    

👉 실생활 상황에 비유

• 메뉴
  • API 문서나 명세서에 해당
  • 사용자(또는 개발자)가 무엇을 선택할 수 있는지, 어떤 서비스나 기능을 요청할 수 있는지 명시되어 있음
• 손님
  • API를 사용하는 개발자나 애플리케이션에 해당
  • 그들은 메뉴(API 문서)를 보고 원하는 것을 선택
• 주문
  • API 호출에 해당
  • 손님(개발자)이 원하는 메뉴(기능)를 선택하고 요청
• 웨이터
  • API 엔드포인트에 해당
  • 손님의 주문(API 호출)을 받아서 주방(서버나 데이터베이스)에 전달
• 주방
  • 백엔드 시스템이나 데이터베이스에 해당
  • 요청받은 주문에 따라 음식(데이터나 서비스 응답)을 준비
• 서비스된 음식
  • API 응답에 해당
  • 웨이터(API 엔드포인트)를 통해 손님(개발자)에게 전달되는 결과물