6.0 6주차 워크북 학습 목표
앞서 4주차에서 학습한 것과 같이 ERD 설계를 마치면,
큰 틀에서 API 설계를 시작해야 한다.
( API 세부사항을 정하기는 어렵겠지만, 큰 틀은 변하지 않는다 )
이번 주차에서는 API 설계 방법을 익히고,
스프링 프로젝트 초기 세팅 방법에 대해 알아보자.
1) RESTful한 API 설계를 익히기
2) Spring boot 프로젝트 세팅하기
6.1 API 란?
프로젝트 개발 과정에서 API 라는 단어를 자주 사용하기도 하고,
대략적으로 클라이언트와 서버 간의 통신에 필요한 것이라는 것은 알고 있지만,
API에 대한 정확한 의미를 이해가 부족하다는 생각이 들었다.
먼저 API의 의미에 대해 정확하게 알아보자.
API ( Application Programming Interface)
- Application을 Programming 할 때 사용되는 인터페이스
- 즉 어플리케이션 프로그래밍을 쉽게 도와주는 도구
예를 들어 Java 에서 println을 통해 콘솔에 출력을 할 때,
우리는 print 함수의 내부 동작에 대해서는 알지 못하지만,
단순히 println 함수를 이용해서 출력을 수행할 수 있다.
이처럼 추상화와 캡슐화를 통해
사용자의 프로그래밍을 쉽게 도와주는 도구를 API 라고 한다.
[ 참고 ] 인터페이스 (Interface) 란?
- 어려운 것을 감추어 쉽게 상호작용 할 수 있도록 도와주는 것
ex ) User Interface (UI)
REST API ( Representational State Transfer )
- HTTP를 기반으로 하는 웹 서비스 아키텍처
- HTTP 메소드와 자원을 이용하여 통신을 주고받는 방법
API Endpoint
- REST API에서 API를 호출하기 위한 HTTP 메서드
- HTTP 메소드와 필요한 자원에 대한 명시를 한 URI를 합쳐서 말함
ex) 도메인 주소가 https://umc.com 일 경우 POST https://umc.com/users/login 을 말함
[ 참고 ] HTTP 메소드란?
- REST 방식으로 통신할 때 필요한 작업을 표시하는 방법
- CRUD 에 대응되는 5가지 메소드가 있음
1) GET : 조회
2) POST : 생성 / 클라이언트가 서버에 특정 정보를 넘기고 처리 요청하는 경우
3) PUT : 갱신 (전체)
4) PATCH : 갱신 (일부)
5) DELETE : 삭제
6.2 RESTful API Endpoint의 설계
API를 설계하기 위해서는
API End point 설계 / 요청 데이터, 응답 데이터 설계 과정이 필요하다.
먼저 RESTful한 API Endpoint를 설계하기 위한 방법을 알아보자.
RESTful API Endpoint 설계 규칙
- URI에 동사가 포함되어서는 안됨
- URI에서 단어의 구분이 필요한 경우 하이픈 ( - ) 사용
- 자원은 기본적으로 복수형으로 표현
- 단 하나의 자원을 명시적으로 표현하려면 식별 값을 추가로 사용 ( ex) /users/id )
- 자원 간 연관 관계가 있는 경우 URI에 표현
- 위의 5개의 규칙을 지키되, 피치 못한 경우는 무조건 따르지 않아도 됨
회원가입, 로그인, 탈퇴 API Endpoint를 설계하여
위의 설계 규칙이 어떻게 적용되는지 알아보자.
회원가입 API Endpoint
- 클라이언트가 로그인 정보를 서버로 넘겨 처리 요청하므로 POST
- 간단하게 POST /users 로 사용 가능
( 요구사항에서 사용자가 새로 추가되는 경우에 대한 명시가 있다면 구분해야 함 )
[ 참고 ] 회원가입은 각각의 유저에 대해 이루어지는데, 왜 POST /users/id 가 아닐까?
- id 값을 사용하려면 해당 유저를 식별할 수 있어야 함
- 회원가입이 진행되기 전에는 유저를 식별할 수 있는 정보가 없음
로그인 API Endpoint
- 클라이언트가 로그인 정보를 서버로 넘겨 처리 요청하므로 POST
- POST /users 의 경우 회원가입의 Endpoint로 사용됨
- POST /users/login 으로 표현
(RESTful API 설계를 타이트하게 따르지 않아도 됨)
회원 탈퇴 API Endpoint
- 회원 탈퇴 시 데이터베이스에서 바로 삭제하는 것이 아님
- 비활성 계정으로 만든 후 계정 복구가 가능해야 하므로 DELETE /users 를 사용하면 안됨
- 즉 사용자 테이블의 status를 active -> inactive로 변경
- PATCH를 사용해야 하므로 PATCH /users로 사용 가능
( 동일하게 특정 유저 정보를 수정해야 하는 '회원 정보 수정'의 경우 PATCH /users/id 사용 )
- 프론트엔드 개발 시 설계를 헷갈려 할 수 있으므로, 추가적인 정보를 더할 수도 있음
6.3 리소스 간 연관 관계가 있는 경우 ( 1 : N 관계 )
한 명의 교사가 여러 개의 교과목을 강의할 수 있다고 가정해보자.
이때 교사과 교과목은 1 : N 관계를 갖게 된다.
여기서 교과목의 목록을 조회하는 API를 설계해보자.
모든 교과목록을 조회하는 경우
1명의 교사가 여러개의 과목을 가르칠 수 있으므로,
위와 같이 교사의 계층관계를 더 높게 잡을 수 있을 것이다.
/users/subjects
특정 교사의 교과목록을 조회하는 경우
만약 특정 교사의 교과목 목록을 보고 싶다면
users 다음에 id를 넣어 특정 교사를 선택할 수 있을 것이다.
/users/id/subjects
하나의 교과목만 조회하는 경우
만약 특정 교사의 특정 교과목으로 설명하는 것이
더 의미 전달이 잘 되는 경우 아래와 같이 설계할 수 있다.
/users/id/subjects/id
혹은 단지 특정 교과목으로만 설명하는 것이
의미 전달이 더 잘 되는 경우 아래와 같이 설계할 수 있다.
/users/subjects/id
6.4 리소스 간 연관 관계가 있는 경우 ( N : M 관계 )
한 개의 게시글에는 여러 개의 해시태그를 달 수 있고,
한 개의 해시태그에는 여러 개의 게시물이 속할 수 있다고 가정해보자.
이때 게시글과 해시태그는 N : M 관계를 갖게 된다.
이 경우에는 둘 사이의 계층 관계를 파악하기 힘들어진다.
이런 경우에는 비즈니스 로직 상 더 중요한 대상을 계층 관계의 앞에 두자!
즉, 위의 경우에서 해시태그보다 게시물이 더 중요한 서비스이므로
게시글을 더 상위 계층으로 표현하는 것이 좋다.
/articles/hash-tag
6.5 세부적인 API 설계하기
앞서 작성한 Endpoint는 단순히 해당 API 의 역할에 대해서만 알려준다.
실제 동작 수행을 위해 필요한 정보를 포함하기 위해서는
아래의 4가지 정보를 포함해야 한다.
API 설계에서 포함해야 하는 키워드
- path variable
- quert string
- request body
- request header
1) Path Variable
- 단 하나, 특정 대상을 지목할 때 사용
- 중괄호 ( { } )로 감싸 식별 값을 표시
예를 들어 게시글 하나만을 조회하는 API를 설계한다고 해보자.
이때 우리는 서버에게 특정 게시글을 식별할 수 있는 데이터를 함께 넘겨주어야 한다.
이를 위해서는 id 에 게시글 식별 값을 같이 전달할 수 있다.
( id 에 들어가는 값은 게시글의 기본키가 된다.)
/users/articles/id
이때 id 는 문자 그대로 id 가 아닌,
게시글의 식별 값을 의미할 것이다.
따라서 API 명세서에는 path variable을 중괄호 ( { } ) 로 감싸 표시하게 된다.
GET /users/articles/{article-id}
이때 id 값을 보다 명확하게 표시하기 위해
article-id (articleId) 로 사용해 주는 것이 좋다.
2) Query String
- 검색 / 조회에 사용
- 따라서 GET 요청에서 주로 사용
- API 엔드포인트에 포함되지 않음
예를 들어 'umc' 단어가 포함된 게시글을 조회한다고 해보자.
해당 경우는 특정 하나의 게시글을 조회하는 것이 아니므로,
path variable이 아닌 query string을 사용하게 된다.
먼저 전달할 정보가 하나인 경우 아래와 같이 나타낼 수 있다.
GET /users/articles?name=umc
만약 전달할 정보가 여러 개인 경우,
& 를 이용하여 전달 값을 연결할 수 있다.
GET /users/articles?name=umc&owner=jimin
단 여기서 query string은 엔드포인트에 포함되지 않으므로,
엔드포인트는 GET /users/articles 임을 유의하자!
3) Request Body
- POST 방식에서 데이터를 URL에 노출하는 것은 굉장히 위험
- request body에 전달하고 싶은 데이터를 담음
- json / form-data 형태로 보냄
회원 가입 과정에서
이름 / 전화번호 / 닉네임을 서버에 전송하는 경우 request body는 아래와 같다.
{
"name" : "유지민",
"phoneNum" : "010-1111-2222",
"nickName" : "yuja",
}
4) Request Header
- 전송에 관련된 메타데이터를 담는 부분
- 로그인을 위한 토큰을 헤더에 담기도 함
6.6 API 설계 예시
사용자 정보인 닉네임을 변경하기 위한 API 설계 예시를 살펴보자.
1) API Endpoint
- PATCH /users/{userId}
2) Request Body
{
"nickname" : "yuja"
}
3) Request Header
Authorization : accessToken (String)
6.7 Spring Boot 프로젝트 세팅
프로젝트 세팅 방법은 아래의 블로그에 정리해 두었다.
[스프링 입문] 섹션 1.3 프로젝트 환경설정 (View 환경설정)
1.3.0 Spring Boot 기능 찾기 Spring은 Java 웹 어플리케이션 개발과 관련된 대부분의 기능을 제공하므로, 방대한 기능을 적절히 사용하기 위해서는, 필요한 기능을 찾을 수 있는 능력이 요구된다. Spring
wlalsu.tistory.com
프로젝트 생성 설정은 아래와 같이 진행하였다.
최용욱 'UMC Server 6주차 워크북' 내용을 기반으로 작성하였습니다.
'[UMC Ewha 5th] Server - SpringBoot' 카테고리의 다른 글
| [UMC Server] Chapter 8.1 API 응답 통일 (2) | 2023.11.27 |
|---|---|
| [UMC Server] Chapter 7. JPA를 통한 엔티티 설계, 매핑 & 프로젝트 파일 구조 이해 (1) | 2023.11.22 |
| [UMC Server] Chapter 5. 실전 SQL - 어떤 Query를 작성해야 할까? (0) | 2023.11.07 |
| [UMC Server] Chapter 4. Database 설계 & AWS RDS 설정 (1) | 2023.11.01 |
| [UMC Server] Chapter 3. Web Server & Web application Server(WAS), Reverse Proxy (1) | 2023.10.09 |