API 설계 및 통신 관련 개념 정리

haruceki·2025년 1월 16일

취업노트

키워드 : RESTful API, GraphQL, OAuth 2.0, 멱등성, HTTP 상태코드

RESTful API의 설계 원칙
- Representational State Transfer : API 설계를 위한 아키텍처 스타일 중 하나로,URI를 통해 자원을 표시하고, HTTP Method를 이용하여 리소스에 접근하며 그 결과를 받는 것을 의미한다.
  - REST 특징
    통일된 인터페이스, stateless(작업을 위한 상태 정보를 따로 저장/관리하지 않음), cacheable(http 캐싱 기능 사용 가능), self-descriptiveness(rest api 메시지만으로 이해 가능한 구조), client-server 구조, 계층형 구조
  - REST API 설계 원칙
    - URI는 정보의 리소스를 명사로 표현해야 한다.
    - 리소스에 대한 행위는 HTTP method로 표현한다 (get, post, put, delete)
    - 슬래시 구분자는 계층 관계를 나타내는데 사용한다
    - 하이픈(-)은 가독성을 높일 경우 사용 가능, 언더바(_)는 사용하지 않는다
    - URI 경로에는 소문자를 사용한다.
    - crud 함수명을 사용하지 말것 (동작이 수행되는지가 아닌 리소스를 가르켜야함)
REST와 SOAP의 차이점
- SOAP(Simple Object Access Protocol) : 그 자체로 프로토콜이며, 보안이나 메시지 전송 등에 있어서 REST보다 더 많은 표준들이 정해져있기 때문에 조금 더 복잡하다.** 이러한 표준들로 인해서 오버헤드가 많기는 하지만, 보안, 트랜잭션, ACID(원자성, 일관성, 고립성, 지속성)을 준수해야 하는 보다 종합적인 기능이 필요한 조직에게는 적합한 방식이 될 수 있다.
- 차이점
  SOAP는 프로토콜이고, REST는 아키텍처 스타일이다. API는 애플리케이션이 서버에 접속할 수 있도록 설계된 일종의 도구이며, SOAP는 서비스 인터페이스를 이용해서 서버에 접근하고, REST는 URI를 이용해서 접근한다.
SOAP는 서버와 매우 긴밀하게 연결되기 때문에 그 통신 방식이 매우 엄격하며, 그래서 수정이나 업데이트를 하는 것이 보다 더 어렵다. REST 방식의 API에서는 클라이언트에서 해당 API가 필요하지 않지만, SOAP 방식의 API에서는 상호작용을 시작할 때조차도 클라이언트에서 API에 관한 모든 정보들을 필요로 한다.

웹 서비스에서는 SOAP가 확실하게 좋은 방법이 아니라면 개발자들이 REST 방식의 API를 택하는 경우가 많으며, 은행용 등 기업용 애플리케이션인 경우에는 보다 많은 리소스와 엄격한 보안 그리고 여러 다양한 요구 사항들을 만족해야 하기 때문에 SOAP 방식을 택하는 경우가 많다.
API 버전 관리의 중요성과 방법
api 경로에 /api/v1 와 같은 버전 정보를 포함시키는 이유는 api의 유지보수성과 확장성을 높이기 위한 전략적 선택이다.
- 장점 : 하위 호환성 유지, 유연한 업데이트 및 테스트, 레거시 시스템 유지, 클라이언트의 명확한 버전 선택
- api 버전 관리 방법
  - URL에 버전 포함(URL versioning) ex- GET /v1/users
  - HTTP 요청 헤더에 버전 포함(header versioning) ex- GET /users Header: Accept-Version: v1
  - 요청 쿼리 파라미터에 버전 포함(query parameter versioning) ex- GET /users?version=1
  - 하위 도메인을 사용 ex- GET https://v1.api.example.com/users
GraphQL과 REST API의 차이점
GraphQL(graph query language)은 API를 위한 쿼리 언어이며 타입 시스템을 사용하여 쿼리를 실행하는 서버사이드 런타임이다. 특정한 db나 특정한 스토리지 엔진과 관계되어 있지 않으며 기존 코드와 데이터에 의해 대체된다.

sql이 db로부터 데이터를 가져오는 목적이라면, GraphQL은 클라이언트가 데이터를 서버로부터 가져오는 것을 목적으로 한다.
- GraphQL과 REST API의 차이
  - REST API는 여러 엔드포인트를 가지며 각각 엔드포인트가 동일한 응답을 하지만, GraphQL은 하나의 엔드포인트만을 사용하며 요청 쿼리에 따라 다른 응답을 반환함.
    - ex
```
REST API
→ example.com/class
→ example.com/class/{반 index}
→ example.com/class/{반 index}/students
→ example.com/class/{반 index}/students/{학생 index}

GraphQL
→ example.com/graphql
(하나의 엔드포인트에 다른 쿼리를 사용해 요청)
```
      REST API의 경우 반에 속해있는 데이터를 가져오는데 응답마다 다양한 엔드포인트를 가지게 된다. 하지만 GraphQL은 하나의 엔드포인트(root endpoint)에 다른 쿼리로 요청함으로써 다른 응답을 받을 수 있다.
  - GraphQL는 원하는 데이터만 받을 수 있다.
    - ex
      - rest api 요청
        // REST API request GET, https://swapi.dev/api/people/1 // REST API response { "name": "Luke Skywalker", "height": "172", "mass": "77", "hair_color": "blond", "skin_color": "fair", "eye_color": "blue", "birth_year": "19BBY", "gender": "male", "homeworld": "http://swapi.dev/api/planets/1/", "films": ["http://swapi.dev/api/films/1/", "http://swapi.dev/api/films/2/", "http://swapi.dev/api/films/3/", "http://swapi.dev/api/films/6/"], "species": [], "vehicles": ["http://swapi.dev/api/vehicles/14/", "http://swapi.dev/api/vehicles/30/"], "starships": ["http://swapi.dev/api/starships/12/", "http://swapi.dev/api/starships/22/"], "created": "2014-12-09T13:50:51.644000Z", "edited": "2014-12-20T21:17:56.891000Z", "url": "http://swapi.dev/api/people/1/" }
      - grapql api
        // GraphQL request query { person(personID: 1) { name height mass } } // GraphQL response { "data": { "person": { "name": "Luke Skywalker", "height": 172, "mass": 77 } } }
- GraphQL 장점 : GraphQL을 쓰면 원하는 정보를 하나의 쿼리에 모두 담아 요청하므로 HTTP 요청 횟수를 줄일 수 있고, HTTP 응답 사이즈를 줄일 수 있으며, rest api와 달리 request/response 형식에 의존하지 않으므로 프론트와 백엔드 개발자의 부담을 덜 수 있다.
- GraphQL 적합한 경우 : 복잡한 데이터 구조 처리(대규모 소셜 플랫폼의 사용자, 게시물, 댓글을 한번에 조회), 클라이언트 주도 개발이 필요시, 실시간 데이터가 필요시(주식, 채팅)
- REST API 적합한 경우 : 단순한 crud 작업, 표준화된 방식이 필요한 경우, 캐싱이 중요한 경우, 빠른 개발 및 유지보수
OAuth 2.0를 사용한 인증 방식
OAuth 2.0(open authorization 2.0)은 인증을 위한 개방형 표준 프로토콜이다. 이 프로토콜에서는 third-party 프로그램에게 리소스 소유자를 대신하여 리소스 서버에서 제공하는 자원에 대한 접근 권한을 위임하는 방식을 제공한다.

구글, 카카오, 네이버 등에서 제공하는 간편로그인 기능도 OAuth2를 기반으로 한다.
- Authentication(인증) : 접근 자격이 있는지 검증
- Authorization(인가) : 자원에 접근할 권한을 부여. 인가 완료시 리소스 접근 권한이 담긴 access token이 클라이언트에게 부여됨
- Access token : 리소스 서버에게서 리소스 소유자의 보호된 자원을 획득시 사용되는 만료 기간이 있는 토큰
- refresh token : access token 만료시 갱신 위한 용도로 사용하는 토큰. access token보다 만료 기간이 길다.
HTTP 상태 코드 중 200, 404, 500의 차이와 각각의 의미
HTTP 상태 코드는 클라이언트가 서버에 요청을 보낼시 서버가 클라이언트에게 응답으로 제공하는 상태 정보를 나타낸다.
- 200 OK : 요청이 성공적으로 처리된 경우
- 404 not found : 클라이언트가 요청한 리소스(URI 경로)가 서버에 존재하지 않는 경우
- 500 internal server error : 서버에서 요청 처리중 내부적으로 오류가 발생한 경우
멱등성(Idempotency)
멱등성이란 연산을 여러 번 수행하더라도 결과가 동일하게 유지되는 특성을 의미한다. 이는 주로 API 설계 및 HTTP 메서드의 동작에서 중요하게 고려된다.
- API 설계 시 멱등성을 고려하는 방법
  1. HTTP 메서드의 의미 준수 : 적절한 메서드 사용
  2. 리소스 중심 설계 : 리소스를 명확히 식별 가능한 URI를 사용
  3. 중복 요청 방지 : 클라이언트 요청마다 고유한 멱등성 키를 생성하여 서버로 전송하여 서버는 이 키를 저장하고, 동일한 키로 들어온 요청에 대해 이미 처리한 응답을 반환
  4. 상태 기반 작업 설계 : 리소스의 상태를 활용하여 작업이 중복되지 않도록 함
  5. 트랜잭션 롤백 처리 : 서버는 요청을 여러 번 처리해도 동일한 상태를 유지하도록 롤백 메커니즘을 구현
API 문서를 자동으로 생성하는 방법(Spring REST Docs 등)
Spring 기반 프로젝트에서는 API 문서를 자동으로 생성하기 위한 도구로는 Spring REST Docs와 Swagger/OpenAPI가 있다.

Spring REST Docs : 테스트 기반 API 문서 생성 도구. RESTful API의 정확한 스펙을 문서화하며, 실제 테스트 코드에서 추출된 정보를 사용하므로 항상 최신 상태의 문서를 보장한다.
- 특징 : API동작을 실제 테스트로 검증하면서 문서를 생성\
- 주요 구성 요소 : JUnit/MockMvc, snippet, AsciiDoc 등이 있다.
Swagger/OpenAPI : API 설계를 문서화하고, 시뮬레이션 및 테스트를 제공하는 자동화 도구 모음. 현재는 OpenAPI 스펙으로 표준화되어, API 문서뿐만 아니라 클라이언트 SDK 생성 및 API UI 테스트를 제공한다.
- 특징 : 자동화된 API 문서화 및 시각화 UI를 제공하며, OpenAPI 표준을 지원
- 주요 구성 요소 : Swagger UI, Springfox/Swagger Annotations

HATEOAS(Hypermedia as the Engine of Application State)
HATEOAS란 RESTful API 설계 원칙 중 하나로, 클라이언트가 서버에서 제공하는 하이퍼미디어 링크를 통해 애플리케이션의 상태 전이를 동적으로 탐색할 수 있도록 하는 개념이다.

HATEOAS는 클라이언트와 서버 간의 결합도를 낮추고, API의 확장성과 유연성을 높이기 위해 사용된다.
- 주요 개념
  - 하이퍼미디어 : api 응답에서 제공하는 링크를 통해 다른 관련 리소스나 작업을 탐색할 수 있는 구조를 의미함
  - 상태 전이 : 클라이언트는 서버가 제공한 링크를 따라가며, 애플리케이션의 상태를 전이하고 필요한 작업을 수행함
  - 자율성 : 클라이언트는 api 응답에 포함된 정보를 통해 api 작동방식을 이해하고 필요한 작업을 수행할 수 있어야 한다.
- 장점 : 확장성, 문서 의존성 감소, 유연성
- 단점 : 복잡성 증가, 클라이언트의 구현 부담, 실무 적용의 한계
- 적용이 필요한 상황 : 동적으로 상태 전이를 지원해야 하는 경우, 복잡한 리소스 탐색이 필요한 경우, api 변경 가능성이 높은 경우
HTTP/2와 HTTP/1.1의 차이점
- HTTP/1.1
  - 헤더와 메시지가 텍스트 기반으로 전송됨. 텍스트 해석이 필요하므로 느림
  - 한 연결에 대해 한 번에 한 요청-응답 처리만 가능 → 지연 있음
  - 각 요청마다 헤더 전체를 전송
  - 여러 요청 처리시 새로운 TCP 연결이 필요하여 TCP 핸드셰이크와 유지비용 증가
  - TLS 사용이 필수는 아님. (프로토콜 차원의 보안 기능 없음)
- HTTP/2
  - 바이너리 기반으로 전송되어 처리 효율 높음. 바이너리 파싱이 간단하고 빠름
  - 단일 연결에서 멀티플렉싱으로 여러 요청-응답 동시 처리
  - HPACK 압축으로 헤더 크기를 최소화
  - 단일 연결로 모든 요청을 처리하여 유지 비용 감소
  - 대부분 HTTPS로만 사용되어 TLS와 결합해 보안 강화

희망도 절망도 없이 매일 코딩을 한다.

이전 포스트

백엔드 프레임워크 관련 개념 정리

다음 포스트

API 설계 및 통신 관련 개념 정리

백엔드 프레임워크 관련 개념 정리

성능 최적화 및 캐싱 관련 개념 정리

0개의 댓글