[미소] 클론코딩 프로젝트 2-1) API 공통 가이드

 

2023.08.09 - [초기 과업/BackEnd] - [미소] 클론코딩 프로젝트 1) 데이터베이스와 API 설계

[미소] 클론코딩 프로젝트 1) 데이터베이스와 API 설계

 

안녕하세요. 기깔나는 사람들에서 백엔드를 맡고 있는 황시아입니다.

 

지난 시간에 위와 같이 데이터베이스와 API 설계를 진행해 보았는데요,

이렇게 하는 것이 아니다. 예제를 보고 다시 해봐라는 피드백을 받아서 처음부터 다시 설계해보려 합니다.

이제 바람직한 방법을 알았으니까... 다시 시작합니다.

 

 

API 개요

 

제가 구현해야 하는 서비스는 미소라는 사이트의 이사 및 청소관련 서비스입니다.

크게는 이용자 서비스와 관리자 서비스로 나누어 구현해야 합니다.

그렇기 때문에 API 설계 또한 이용자와 관리자 서비스 두 가지로 나누어서 진행할 것입니다.

 

 

API 공통 가이드

 

API 공통 가이드는 이사 및 청소관련 API(이하 미소 API)를 사용하여 개발할 때 미리 알아야 하는 내용을 설명합니다.

 

API 공통 사항

공통 사항	설명
HTTP 사용 가능	미소 API는 HTTP 사용이 가능합니다.(HTTPS는 적용 예정)

 

API Base URL

이름	Base URL	PORT	비고
local 환경	http://localhost	8080

 

API Request

미소에서 제공하는 API 요청 URL 형태는 다음과 같습니다. HTTP에서 파라미터를 다음과 같은 방법으로 전달할 수 있습니다.

 

API 호출 방식

미소의 Web API 호출 방식을 일반적으로 application/json 방식을 사용합니다.

메서드	구분	파라미터 전달
GET	URL	요청 URL에 표기된 쿼리 파라미터
POST	Body	Request Body에 application/json으로 표현된 데이터 multipart/form-data로 이미지 전송
PUT	Body	Request Body에 application/json으로 표현된 데이터
PATCH	Body	Request Body에 application/json으로 표현된 데이터
DELETE	Body	Request Body에 application/json으로 표현된 데이터

 

API 인증

미소의 API는 이용자가 로그인 시에 자동으로 부여받은 JWT key를 HTTP 요청(Request)의 Authorizartion 헤더를 통해 전달하여 이용자를 인증합니다. 인증이 필요하지 않은 API는 해당 헤더를 포함할 필요는 없습니다.

curl -X POST http://localhost:8080 \
   -H "Authorization: Bearer {YOUR_JWT_KEY}"

 

API Response

모든 ITDING API 응답(Response)는 아래 테이블과 같은 구조를 가지는 JSON 객체로 표현됩니다. 따라서 Content Type은 application/json 으로 고정됩니다.

 

공통 Response

필드	타입	필수 여부	설명	비고
statusCode	Integer	필수	API 호출 상태	200: 작업 성공 201: 등록 성공 400: 잘못된 요청 401: 접근 불가 500: 서버 문제
message	String	필수	API 호출 상태 설명
data	Object Object[]	선택	API 응답 데이터	API 응답 데이터 존재 시 제공
pagenation	Object	선택	API 응답 Page 데이터	API 응답 Page 데이터 존재 시 제공

 

공통 Response 응답 예시

{
    "statusCode": 200,
    "message": "성공"
}

 

필드 타입 표기

API 응답의 타입은 아래 표를 따릅니다.

타입 표기	설명
Integer	수
Boolean	true 또는 false 값
String	문자열
Timestamp	ISO 8601로 표현된 숫자 (ex. 2022년 12월 7일 18시 0분 0초 → 2022-12-07T18:00:00+09:00)
{Type}[]	특정 타입의 값을 요소로 갖는 배열(Array), 배열 타입의 값이 없을 때 null 이 아닌 빈 배열([])로 표현
Multipart File	Multipart file

 

Pagination

Pagination이 적용된 목록 조회 API는 아래와 같은 규칙이 적용됩니다.

 

Request

목록 조회 단위인 page와 size를 쿼리 파라미터로 요청합니다.

# page=3, size=10으로 조회
  curl -X GET https://localhost:8080/posts?page=3&size=10 

# page=1, size=20으로 조회(기본값)
  curl -X GET https://localhost:8080/posts

 

Response

Pagnation Object에 대한 상세는 다음과 같습니다.

파라미터	타입	필수 여부	설명
pageSize	Integer	필수	한 페이지의 element 갯수
totalPages	Integer	필수	전체 페이지의 갯수
totalElements	Integer	필수	전체 element의 갯수
currentPage	Integer	필수	현재 페이지 위치
currentElements	Integer	필수	현재 페이지의 element의 갯수

 

Pagination이 적용된 목록 조회 API의 응답 예시

{
    "statusCode": 200,
    "message": "성공",
    "data": {
        // 데이터 생략
    }
    "pagenation": {
        "pageSize": 20,
        "totalPages": 20,
        "totalElements": 149,
        "currentPage": 8,
        "currentElements": 9
    }
}

 

다음부터는 본격적으로 각 기능의 API 명세를 만들어 보겠습니다.