[TIL] REST API와 RESTful API설계 방법

냠냠빈·2024년 12월 19일

API GET POST REST REST API delete http http메소드 put restful api

📚📆 프로그래머스 백엔드 부트캠프 TIL

목록 보기

17/28

🌐 REST API란 무엇인가?

REST API는 Representational State Transfer (REST) 아키텍처 스타일을 따르는 애플리케이션 프로그래밍 인터페이스(API)입니다. 클라이언트와 서버 간의 통신을 위해 설계되었으며, 주로 HTTP를 기반으로 동작합니다.

REST는 리소스를 URI로 식별하고, 특정 리소스에 대해 CRUD 작업(Create, Read, Update, Delete)을 HTTP 메소드로 표현합니다. 이를 통해 RESTful하게 설계된 API는 가독성과 유지보수성이 뛰어나며, 표준화된 방식으로 데이터를 주고받을 수 있습니다.

Representational State Transfer API
자원(resource)의 표현(representation)에 의한 상태 전달을 뜻한다.

자원 : 해당 소프트웨어가 관리하는 모든 것 ( 문서, 그림, 데이터, 해당 소프트웨어 자체 등 )

표현 : 그 자원을 표현하기 위한 이름 ( DB의 학생 정보가 자원이면, 'students'를 자원의 표현으로 정함 )

상태 전달 : 데이터가 요청되는 시점에 자원의 상태를 전달한다. ( JSON 혹은 XML을 통해 데이터를 주고 받는 것이 일반적 )

🔑 REST의 개념과 특징

클라이언트-서버 구조
- 클라이언트와 서버를 분리하여 독립적으로 동작할 수 있게 설계합니다.
무상태성 (Stateless)
- 서버는 클라이언트의 상태를 저장하지 않으며, 각 요청은 독립적으로 처리됩니다.
캐싱 가능
- HTTP 프로토콜의 캐싱 기능을 활용하여 클라이언트 성능을 향상시킬 수 있습니다.
통합된 인터페이스
- URI와 HTTP 메소드를 통해 리소스에 접근할 수 있으며, 일관된 방식으로 데이터를 주고받습니다.
계층 구조
- 시스템은 여러 계층으로 나뉘어 있어, 클라이언트와 서버 간의 중간 계층(예: 로드 밸런서)을 추가할 수 있습니다.

🚀 HTTP 메소드와 RESTful 동작

HTTP 메소드는 REST API에서 리소스를 다루기 위해 사용됩니다. 주요 메소드는 다음과 같습니다:

GET: 리소스 조회
POST: 리소스 생성
PUT: 리소스 전체 수정 (또는 생성)
PATCH: 리소스 부분 수정
DELETE: 리소스 삭제

예시

GET /users
POST /users
PUT /users/1
DELETE /users/1

🖋️ RESTful API 설계 시 주의할 점

기본적으로 Restful API 설계 시 규칙은 다음과 같습니다.

의미를 바로 알아볼 수 있도록 작성하고, 소문자를 사용한다.
❌ GET /users/writing
❌ GET /users/Post-Comments
⭕ GET /users/post-comments

URI가 길어지는 경우 언더바(_) 대신 하이픈(-)을 사용한다.
❌ GET /users/profile_image
⭕ GET /users/profile-image

마지막에 슬래시(/)를 포함하지 않는다.
후행 슬래시(/)는 의미가 전혀 없고 혼란을 야기할 수 있다.
❌ GET /users/
⭕ GET /users

리소스에 대한 행위를 HTTP Method로 표현한다.

URI에 HTTP Method가 포함되서는 안된다.
❌ get/users/
⭕ GET /users/

resource는 동사가 포함되서는 안되고 명사를 사용한다.
❌ GET /users/show/1
⭕ GET /users/1

파일 확장자는 URI에 포함시키지 않는다.
❌ GET /users/photo.jpg
⭕ GET /users/photo (이때, payload의 포맷은 headers에 accept를 사용한다.)

URI 사이에 연관 관계가 있는 경우 /리소스/고유ID/관계 있는 리소스 순으로 작성한다.
❌ GET /users/profile/{user_id}
⭕ GET /users/{user_id}/profile

URI에 작성되는 영어를 복수형으로 작성한다.
❌ GET /product
⭕ GET /products

URI는 / 구분자를 사용하여 자원의 계층 관계를 나타내는데 사용한다.

출처: CS | API, REST API, REST 설계 규칙 - happy tiger

그렇다면 주의할 점은 뭘까요?

URI 설계
- 동사 대신 명사를 사용 (예: /createUser 대신 /users)
- 복수형 명사 사용 (예: /users)
HTTP 상태 코드
- 200: 요청 성공
- 201: 리소스 생성
- 400: 잘못된 요청
- 404: 리소스 없음
- 500: 서버 오류

일관된 데이터 포맷
- JSON을 기본 데이터 포맷으로 사용
- 예:
```
{
 "id": 1,
 "name": "John Doe"
 }
```

💻 실무에서 REST API 활용

Spring Data JPA와 REST API 연동
Spring Data JPA를 사용하여 데이터베이스와 통신하고, REST API를 통해 클라이언트에 데이터를 제공합니다.

예:

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserService userService;

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.saveUser(user);
    }
}

Swagger와 API 문서화
API 명세를 자동화하기 위해 Swagger를 사용합니다. 이를 통해 팀원들과 클라이언트가 API를 쉽게 이해할 수 있습니다.
보안 강화
- 인증 및 권한 부여 (예: OAuth 2.0, JWT)
- HTTPS 적용

⚡ REST API와 기타 개념 비교

항목	REST API	SOAP
설계 스타일	REST (아키텍처 스타일)	프로토콜 기반
데이터 포맷	주로 JSON	XML
유연성	높음	낮음
사용 사례	웹 및 모바일 애플리케이션	금융, 결제 등 높은 신뢰성이 요구되는 시스템