본문으로 건너뛰기

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

5.4. JSON 스키마​

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

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

5.5. 상태 코드​

상태 코드 카테고리

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

자주 사용사되는 상태 코드

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

5.6. 미디어 타입(MIME)​

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

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

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

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