❗HTTP 통신을 먼저 알고 오셔야 이 글이 이해가 됩니다!
📢 REST API의 필요성
웹 서비스를 제작하는데, Frontend인 React와 데이터를 어떻게 주고 받을까 고민했다.
기존의 JSP에서는 내장객체로 전달하는 장점이 있지만, React에서는 어떻게 할까?
정해진 아키텍처를 사용하면, backend에서도 frontend에서도 편하다.
간단한 예시를 보자.
이런 느낌인 것이다. 사람과 사람사이에는 연락 수단(카톡, 메일)이 있지만,
Frontend와 Server 사이에 정보를 요청하고 전달하는 약속이라고 생각하면 편할 것 같다.
🤔 근데 REST API가 뭔데?
Representational State Transfer API
우리는 웹에서 HTTP 통신을 한다.
REST는 자원의 이름으로 구분해 해당 자원의 상태를 주고 받는 모든 것을 의미한다.
REST는 자원, 행위, 표현으로 이루어져있다.
1. 자원 : URI
- 자원은 고유 이름이라고 보면 될 것 같다.
ex ) 고객 → user
2. 행위 : HTTP Method
Method를 이용하여 CRUD의 기능을 구현합니다.
GET/POST/PUT/DELETE/OPTION- [주로 사용]
GET: 정보 조회 /POST: 리소스 생성
3. 표현 : Representation of Resource
- 클라이언트와 서버 사이에 주고 받을 때 자원의 상태를 의미한다.
JSON, XML, TEXT로 사용하곤 한다.
REST API 설계 원칙
REST API 설계 시 중요한 것은 명확해야한다.
- URI는 정보의 자원을 나타내야함
- 자원의 행위는 HTTP Method(
GETPOSTPUTDELETEOPTION)로 나타내야한다.
예를 들어보자.
내가 고객의 정보를 조회하고 싶다하면 아래와 같이 나타내면 된다.
URI의 설계 규칙
1. URI는 소문자로만 구성한다.
대문자는 때로 문제를 일으키는 경우가 있어 소문자를 선호한다.
2. URI에는 행위를 포함하지 않는다.
URI는 명사만 사용하며, 행위는 Method로 표시해야 한다.
❌ GET /getUser/:id
⭕ GET /user/:id
3. 언더바(_) 대신 하이픈(-)을 사용한다.
언더바는 글자 폰트에 따라 부분적으로 가려지거나 숨겨질 수 있다.
가독성을 위해 긴 단어는 하이픈으로 구분하는 것이 좋다.
4. 슬래시(/)는 계층 관계를 표현한다.
슬래시는 URI 경로 부분에서 자원 간의 계층적 관계를 나타내기 위해 사용한다.
http://api.example.com/students/3 -> 3번 학생
5. URI의 마지막 문자로 슬래시(/)를 포함하지 않는다.
마지막 슬래시는 의미가 없으나 혼란을 가져올 수 있다.
❌ http://api.example.com/students/
6. 파일 확장자는 URI에 포함 시키지 않는다.
파일 확장자는 URI 대신 Content-Type 헤더를 통해 전달 되는대로 미디어 타입을 사용하여 body 콘텐츠를 처리하여야 한다.
Accept Header를 통해 응답으로 받고 싶은 미디어 타입을 명시한다.
❌ http://api.example.com/sutdents/photo.jpg
7. URI에서 영어는 복수형으로 작성한다.
복수형으로 사용하는 것이 실무에서 많이 사용되고 있다.
🤔 그럼 설계를 어케함?
여기서는 내가 경험했던 [가게 앞 웨이팅 등록 시스템] 프로젝트를 토대로 이야기 해보겠다.
1. 구현할 기능 정리
구현할 기능들을 정리해두는 것이 좋다. 나의 경우 Notion에서 기능 명세서를 작성했다.
기능 별로 설명이나, 액터(사용자), 기능할 구현들을 간단하게라도 정리하는 게 좋다.
이렇게 정리해 두고 Frontend 개발자와 Backend 개발자 서로 보면서 각자 개발할 내용을 서로 공유한다.
논의 한 후에 구현할 기능을 확정한다.
2. API 명세서 작성하기
정리해둔 기능을 토대로 API 명세서를 작성한다.
위에 나왔던 HTTP Method + URI 로 구성되어 있다.
노션 템플릿은 인터넷에 공유되어 있었다.
3. 상세 API 설계하기
REST API는 Frontend와 Backend 사이에 요청을 주고 받기 위한 수단이므로,
FrontEnd 개발자들은 이 문서를 보고 서버에 정보를 요청한다.
그러니 설명, 요청 예시, 요청 시 담아야할 데이터, 응답 예시 등을 작성해두면 좋다.
아래는 JSON 형태로 전달하는 API 형태이다.
상태에 맞는 여러 코드도 전달해야 하는데, 코드 번호는 HTTP 상태 코드 사이트 에서 확인 가능하다.
적절한 상황에 맞게 코드도 전달해보자.
로그인 기능 API 문서
| 설명 & 요청 예시 | 응답 예시 | 응답 예시 |
|---|---|---|
 |  |  |
실제 Spring 코드와 API 사용은 다음편에 살펴보자.
참고
