[실전 API 설계] - 05. API 응답 기술하기

5.4. JSON 스키마

type 필드는 모든 JSON 스키마에서 필수 필드로, 데이터의 타입을 선언함

type: object
properties: // 필드를 지정
  rating: // 필드 이름
    type: integer // 필드의 값의 타입
    minimum: 1
    maximum: 5

5.5. 상태 코드

상태 코드 카테고리

범위	카테고리	참고
1xx	Informational	서버가 요청을 받았다는 임시 응답
2xx	Success	200 OK나 201 Created처럼 요청 성공
3xx	Redirects	요청 자원의 위치/URI가 변경됨
4xx	Client error	클라이언트가 제공한 요청 정보에 오류가 있음
5xx	Server error	서버 처리 과정에 오류가 있음

자주 사용사되는 상태 코드

범위	카테고리	참고
101	Switching protocols	웹소켓 프로토콜로 업그레이드될 때
200	Ok	요청 성공
201	Created	요청 결과 새 자원 생성
301	Moved permanently	요청한 URL에 해당하는 자원이 새로운 URL로 영구적으로 이동
403	Forbidden	권한 부족
404	Not found	요청한 자원이 존재하지 않음
504	Gateway timeout	프록시나 게이트웨이가 백엔드 서버에 도달하지 못하고 타임아웃

5.6. 미디어 타입(MIME)

HTTP에서 데이터 형식을 알려주기 위해 Content-Type 헤더에 미디어 타입 또는 MIME로 데이터 형식을 명시함.

미디어 타입은 '타입'과 '서브타입', 선택적 파라미터로 구성됨.

미디어 타입	설명
text/html	웹 서버가 반환하는 HTML
text/csv	쉼표로 구분된 값
image/png	PNG 형식으로 인코딩된 이미지
application/json	JSON 데이터
application/xml	XML 데이터

5.7. GET /reviews 응답 기술하기

paths:
  /reviews:
    get:
      responses:
        '200':
          description: A list of reviews
          content: // 응답 본문을 작성
            applications/json: // 응답 본문의 미디어 타입
              schema:
                type: array
                items:
                  type: object
                  properties:
                    rating:
                      type: integer
                      minimum: 1
                      maximum: 5

JSON 스키마와 OpenAPI 방식 JSON 스키마의 차이로 nullable이 있다. JSON 스키마는 배열로 여러 타입을 지정할 수 있지만, OpenAPI는 여러 타입을 지정할 수 없음. 이에 null 허용 여부는 필요하므로 nullable 키워드가 추가됨

type: string
nullable: true