우리가 어떤 웹사이트를 만들고, 서비스하기 위해서는 많은 설계가 필요하다.
웹페이지를 어떻게 디자인해서 사용자의 웹 브라우저에 보여줄지에 대해서도 생각해야하고,
사용자로부터 어떤 값을 입력받고 어떤 값들을 서버 측으로 전달해줄지에 대해서도 생각해야하고,
전달받은 값들을 어떻게 처리해야 하며, 클라이언트에게 돌려줘야 할 값들에 대해서도 생각해야한다.
오늘은 이 중에서도, 어떤 값들을 전달받고 어떤 값들을 돌려줘야할지에 대하여 API 설계를 공부해보고자 한다.
API 설계
백엔드에서 API를 설계할 때에는 다음의 사항들을 고려해야 한다.
- HTTP Method
- URI
- HTTP Status Code
- Request Body 값
- Response Body 값
예를 들어, 쇼핑몰 사이트를 생각해보자.
사용자는 구글에서 쇼핑몰의 이름을 검색해서 URI (ex. www.shoppingmall.com)에 접속한다.
이것은 클라이언트가 GET메소드로 서버에 /shoppingmall(아이피 주소) 를 통해 Request 를 보내는 것을 의미한다.
서버측에서는 프론트엔드에게 메인페이지에서 보여질 값들을 담아서(Response Body)
200 status code를 전송한다.
프론트엔드는 이 값들을 잘 정리해서, 최종적으로 사용자의 웹브라우저의 UI에 뿌려준다.
즉, API 설계에 있어서 위의 5가지 항목들에 대해서는 필수적으로 고려를 해야한다.
위 5가지를 고려하여, 쇼핑몰의 회원가입 API에 대해 설계해보자.
| HTTP Method | POST |
|---|---|
| URI | /join |
| Status Code | 201 |
| Request Body | email, name, password, contact |
| Response Body | - |
| 추가 고려사항 | header를 통해 JWT 전달 |
-
HTTP Method
회원가입은 데이터베이스 서버에 회원의 값들을 INSERT하는 것이기 때문에,
Request Body에 회원에 대한 정보들을 담아서 서버로 Request를 보내야 한다.
따라서 HTTP Method는POST를 이용한다. -
URI & Reqeust Body
회원이 회원가입 페이지에서 정보를 입력하고회원가입 버튼을 누르면,
/join 이라는 URI를 통해 POST Request를 보내게 된다. 이 때, 입력한 정보들을 기반으로
이메일, 이름, 비밀번호, 연락처 정보를 Request Body에 담아서 서버로 전달한다. -
Status Code
서버는 이를 수신하고, 올바른 데이터인지 유효성 검사를 수행한다.
올바르지 않다면 400 bad response를 프론트엔드에 전달한다.
올바르다면, 데이터베이스에 회원의 정보를 저장하고 201 response를 프론트엔드에 전달한다. -
Response Body
Response Body에는 딱히 돌려줄 값이 없다.
회원가입이 완료된 후의 새로운 페이지로의 전환이나, 팝업을 띄우는 것은 프론트엔드 측에서 처리할 것이다. -
추가 고려사항
회원가입이 완료된 후에, 로그인이 된 상태로 메인페이지로 이동시켜 주고 싶다면,
로그인이 된 상태라는 JWT 를 Header부분에 담아서 보내주면 된다.
(하지만, 웹사이트에 회원가입을 하면 저절로 로그인시켜주는 페이지는 많이 없던 것 같다.
로그인 API를 설계할 때, JWT를 발행해준다는 것을 의식하고 있으면 될 것 같다.)
* API의 설계는 계속해서 수정하며 설계한다.
예를 들어, 내가 VIP 시스템을 도입하기 위해서 사용자의 구매횟수에 대한 데이터 값이 필요해질 수 있다.
이 구매횟수에 대한 값들은 어떤 테이블에 추가 해야할지, 어떤 API를 이용할 때 값이 불러와질지 등 계속 해서 수정하면서 진행해야 한다.
데이터베이스 설계 / ERD 작성
API를 설계하다 보면 느낄 수 있겠지만, Request 받은 값들을 응용하기 위해서는 데이터베이스에 저장해야할 수 밖에 없다.
따라서, API설계와 데이터베이스 설계는 동시에 이루어진다.
아래 사이트는, 표 형식으로 데이터베이스의 ERD를 작성할 수 있는 사이트이다.
dbdiagram.io
아래는, dbdiagram의 기본 예시 ERD이다.
간단한 코드 작성을 통하여 테이블을 생성할 수 있고, key값이나 primary key 지정, 연관관계(1:N 등)를 표현할 수 있다.
예를 들어, 우리가 살펴보았던 회원가입에 대한 ERD를 그려보면 다음과 같다.
* 테이블명은 보통 복수형(s)의 형태로 작성하는 경우가 대부분이다.
이렇게 API를 설계하면서 필요한 데이터베이스의 ERD를 작성하면,
작업에 혼선을 최소화하여 명확하게 진행할 수 있다.
정리
오늘은 API 설계를 어떻게 수행하는 지 살펴보았다.
데브코스에서는 이런 간단한 API뿐만 아니라, 도서 사이트의 API를 설계해보고 있다.
쇼핑몰 사이트도 마찬가지이겠지만,
회원가입 API 뿐만아니라 내 정보를 조회하는 API, 물품을 조회하는 API, 장바구니를 조회하는 API, 장바구니의 선택 항목들을 결제하기 위한 API 등 엄청나게 많은 API들이 모여 웹사이트를 구성하게 된다.
이에 따라 데이터베이스 테이블도 엄청나게 많아지고, 데이터도 엄청나게 많아진다.
이렇게 본격적으로 하나의 웹사이트의 API설계를 수행해보는 것은 처음이라 많이 어렵게 느껴지지만,
프로젝트를 수행하면서 많은 경험을 쌓는 것이 API설계에 도움이 될 것 같다.
