[실전 API 설계] - 01. API와 OpenAPI 소개

1.3. OpenAPI란?

RESTful API를 포함하는 HTTP 기반 API를 기술하는 명세

OpenAPI는 YAML이나 JSON 형식으로 작성되어 API의 입력/결과를 기술.
API의 호스팅 위치, 접근 권한 등 API 생산자와 소비자 모두에게 필요한 정보를 포함.

1.3.1. OpenAPI 정의서 예제

정의서를 통해서 확인할 수 있는 정보들

• API의 호스팅 주소
• 요청 방식과 요청 경로
• 파라미터 정보
• 리턴값의 형태

1.4. OpenAPI 정의서는 어디에 사용하는 것이 좋을까?

API 정의서로 더 거대한 추상화, 더 자동화된 워크플로를 만들 수 있다.

OpenAPI 워크플로 예시

• API 문서, 서버 스텁, 클라이언트 SDK로 변환
• API 테스트 일부 자동화
• API 설계 조기 피드백
• API 일관성 보장
• 버전별 API 변경사항 비교

1.5. 스웨거란?

스웨거 프로젝트는 스웨거 UI와 YAML 파일 작성 가이드로 시작해 명세와 표준이 됨. 이런 도구와 명세를 합쳐 스웨거라고 부름.

2015년, 스웨거 프로젝트가 스마트베어에 인수되며 명세 부분은 리눅스 파운데이션에 기부되어 OpenAPI로 이름이 바뀜.

1.6. REST란?

REST는 네트워크로 연결된 시스템 설계 방법에 대한 아이디어 모음으로, 대부분의 웹 서버는 RESTful API가 사용됨.

실무에서는 HTTP 기반 API 설계 시, 요구사항과 표준 또는 REST 원칙 준수 사이에서 트레이드오프를 고려해야 함.

REST는 API와 API를 공급하는 서비스를 분리하는 데 목표를 두고 있다. REST는 요청-응답 모델을 사용하며, 처리에 필요한 모든 정보가 요청에 포함돼 있으므로 상태를 별도로 관리하지 않는 무상태 방식.

REST의 핵심 아이디어 중 하나는 자원으로, 각 자원은 URI에 의해 식별될 수 있음. 예로 사용자 계정은 /users/123이라는 URI를 가질 수 있으며, API안에서 유일하게 식별할 수 있는 자원을 의미함.

REST와 HTTP를 명확하게 경계 짓기는 어렵지만, HTTP는 프로토콜, REST는 API를 기술하는 방식으로 이해하면 됨. 둘은 밀접한 관계가 있으며 REST 설계 패턴을 따르지 않는 HTTP API를 RESTful하지 않다고 표현함.

REST 원칙:
2000년 네트워크 시스템에 관한 로이 필딩의 논문에서 처음 소개

1.7. OpenAPI는 언제 사용하는가?

하이퍼미디어:
문맥을 이해할 수 있는 링크를 URI의 형태로 반환하는 시스템

1.7.1. API 사용자

API 사용시 가장 먼저 찾아보는 것은 사용 언어로 작성된 SDK인데, 다수의 언어로 SDK가 만들어져 있지 않을 수 있음. 이런 상황에서 API가 OpenAPI로 기술되어 있다면 여러 언어로 SDK를 자동으로 만들 수 있음. 스웨거 코드젠이나 OpenAPI 제너레이터 같은 도구가 제공하는 SDK 템플릿을 활용할 수 있음.

1.7.2. API 제공자

OpenAPI 정의서를 사용해 준비 코드와 스텁을 자동으로 생성할 수 있어 템플릿을 커스터마이징해 생산성과 일관성을 높일 수 있음.

다음과 같은 방식으로 API를 개발할 수도 있음

• 런타임에 OpenAPI 정의서로 API 연산과 클래스 및 메소드를 매핑하는 라우터로 사용
• 입력값이 OpenAPI 정의서의 스키마에 부합하는지 확인하는 검증 계층으로 사용

1.7.3. API 설계자

OpenAPI는 API 제공자와 사용자 사이에서 의사소통을 돕는 매체 역할을 함.
OpenAPI 정의서로 API의 패턴을 파악하면 모든 API를 일관성 있는 패턴으로 표준화할 수 있다.