REST API와 RESTFUL API

January 9, 2023

면접을 보고왔는데 REST API와 RESTful API에대한 질문을 받았다.
이제까지 프로젝트를 REST API로 설계했기떄문에 HTTP 메소드를 통해 자원을 처리하는것이라고 대답하였는데, RESTAPI와 RESTFULAPI가 조금 다르다는 말을 들었다. 뭐가 다른걸까?

1. REST API(Representational State Transfer API)

REST API는 네트워크 아키텍처 원칙을 기반으로 한 API 스타일이다
자원(Resource)을 URI로 표현하고,
HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 조작하는 방식을 따른다
REST API는 클라이언트와 서버 간의 통신을 위한 규칙을 제공한다
데이터 포맷으로는 주로 JSON이나 XML을 사용한다

2. RESTful API

REST API를 따르는 API 디자인의 원칙을 지킨 API
자원을 URI로 표현하고, HTTP 메서드를 사용해 CRUD(Create, Read, Update, Delete) 기능을 구현한다.
URI는 자원을 명확하게 표현해야 하며, 명사 형태로 표현되어야 한다.
HTTP 상태 코드를 이용하여 요청의 성공, 실패를 표현한다.

간단히 말해, REST API는 웹 서비스를 개발하는 데 사용되는 디자인 원칙을 의미하며, 이를 준수하여 만든 API가 RESTful API라고 할 수 있다.

HATEOAS

Hypermedia As The Engine Of Application Stata는 RESTful API의 중요한 원칙 중 하나
클라이언트가 API를 통해 가능한 다음 단계를 자동으로 파악할 수 있도록 하여
애플리케이션 상태 전이를 단순화하는 기능을 제공하는것
즉, 각 요청의 응답에 사용가능한 다른 요청들의 정보를 포함시키는것

이는 보내는데이터에 연계된 다른 정보들을 함꼐 보냄으로써,
개발자는 API 문서를 확인하지않고도 다음에 어떤 요청을 보낼수 있는지 살펴 볼 수 있다

아래의 예제는 클라이언트가 자원을 특정할 수 있는 URL을 제공하고,
해당 자원에 대해 가능한 동작을 설명함으로써 HATEOAS 원칙을 준수하고 있다

{
  "id": 1,
  "name": "John Doe",
  "age": 30,
  "links": [
    {
      "rel": "self",
      "href": "https://api.example.com/users/1"
    },
    {
      "rel": "update",
      "href": "https://api.example.com/users/1",
      "method": "PUT",
      "type": "application/json",
      "description": "Update this user's information"
    },
    {
      "rel": "delete",
      "href": "https://api.example.com/users/1",
      "method": "DELETE",
      "description": "Delete this user"
    }
  ]
}

self 링크: 자원 자체를 가리키며, 이를 통해 자원의 식별과 접근 가능
update 링크: PUT 메서드를 통해 해당 자원을 업데이트할 수 있는 URL을 제공
delete 링크: DELETE 메서드를 통해 해당 자원을 삭제할 수 있는 URL을 제공

REST 방식 API 설계

1. CRUD

REST로 표현하는 자원들은 대부분 복수형으로 경로를설계한다

경로	메서드	설명
`/users`	GET	모든 사용자 목록 조회
`/users`	POST	새 사용자 등록
`/users/{id}`	GET	특정 사용자 조회
`/users/{id}`	PUT	특정 사용자 정보 전체 수정
`/users/{id}`	PATCH	특정 사용자 정보 부분 수정
`/users/{id}`	DELETE	특정 사용자 삭제

1. Query String(쿼리스트링)

URL에서 ? 뒤에 오는 키=값 형태의 문자열들
여러 개의 값을 연결할 땐 &로 구분
고정된 방식이 없는 REST의 기본 설계 원칙과 잘 어울리는 유연한 방식

주로 GET 요청에서 사용

GET /users?age=20&gender=male&page=2&sort=name

구분	예시	사용 목적
Path Variable	`/users/1`	특정 “자원”을 식별할 때
Query String	`/users?age=20&sort=name`	“조건”, “필터”, “기능” 등 부가 정보 제공 시

HTTP 상태 코드 (HTTP Status Codes)

클라이언트(브라우저, API 요청 등)의 요청에 대한 서버의 응답 상태를 나타내는 숫자 코드
클라이언트가 서버에 요청을 보냈을 때, 그 요청이 성공했는지, 실패했는지, 추가 작업이 필요한지를 알려준다
HTTP 상태 코드는 5가지 범주로 나뉜다.

상태 코드 범위	설명
1xx (정보)	요청을 받았고, 처리가 진행 중
2xx (성공)	요청이 성공적으로 처리됨
3xx (리다이렉션)	추가 작업이 필요하거나, 다른 URL로 이동
4xx (클라이언트 오류)	클라이언트의 요청에 문제가 있음
5xx (서버 오류)	서버에서 요청을 처리하는 중 문제가 발생

✅ 1xx: 정보 응답 (Informational Response)

요청을 받고, 처리를 진행중

상태 코드	의미
100 Continue	요청의 일부를 받고 문제없으니 계속 요청하라는 의미
101 Switching Protocols	클라이언트가 요청한 프로토콜로 변경 중
103 Early Hints	최종 응답 전에 일부 헤더 정보를 미리 제공

✅ 2xx: 성공 (Success)

요청이 성공적 처리됨

상태 코드	의미
200 OK	요청이 성공적으로 처리됨
201 Created	새로운 리소스가 성공적으로 생성됨 (POST 요청 시)
202 Accepted	요청이 접수되었으나 처리가 완료되지 않음
204 No Content	요청은 성공했지만 반환할 데이터가 없음 (예: DELETE 요청)

✅ 3xx: 리다이렉션 (Redirection)

클라이언트가 다른 곳으로 이동해야함

상태 코드	의미
301 Moved Permanently	요청한 리소스가 영구적으로 새로운 URL로 이동됨
302 Found	요청한 리소스가 일시적으로 다른 위치에 있음
303 See Other	클라이언트가 GET 요청을 다른 URL로 다시 보내야 함
304 Not Modified	캐시된 데이터가 최신 버전이므로 새로 다운로드할 필요 없음

✅ 4xx: 클라이언트 오류 (Client Error)

요청에 문제가 있음

상태 코드	의미
400 Bad Request	잘못된 요청 (예: JSON 형식 오류, 필수 데이터 누락)
401 Unauthorized	인증되지 않은 요청 (로그인 필요)
403 Forbidden	접근 권한 없음 (예: 관리자 전용 페이지)
404 Not Found	요청한 리소스를 찾을 수 없음
405 Method Not Allowed	허용되지 않은 HTTP 메서드 사용
409 Conflict	리소스 간 충돌 발생 (예: 중복된 데이터)
429 Too Many Requests	너무 많은 요청을 보냄 (Rate Limit 초과)

✅ 5xx: 서버 오류 (Server Error)

서버 내부 문제로 요청 처리가 실패함

상태 코드	의미
500 Internal Server Error	서버 내부 오류
502 Bad Gateway	게이트웨이(프록시 서버)에서 응답을 받을 수 없음
503 Service Unavailable	서버가 일시적으로 사용할 수 없음
504 Gateway Timeout	게이트웨이가 응답을 기다리다가 시간 초과

🚀 실무에서 자주 쓰이는 상태 코드

✅ 200 OK → 정상 응답
✅ 201 Created → 새로운 리소스 생성 (POST)
✅ 204 No Content → 응답 데이터가 필요 없음 (DELETE)
✅ 400 Bad Request → 잘못된 요청 (입력값 오류)
✅ 401 Unauthorized → 로그인 필요
✅ 403 Forbidden → 권한 없음
✅ 404 Not Found → 리소스 없음
✅ 500 Internal Server Error → 서버 내부 오류

✅ 정리

HTTP 상태 코드는 클라이언트 요청에 대한 서버의 응답 상태를 나타내는 코드 이다 REST API는 이 상태코드를 사용하여 간단하게 에러처리를 할 수 있다

1xx → 정보
2xx → 성공
3xx → 리다이렉션
4xx → 클라이언트 오류
5xx → 서버 오류

이 중에서도 200, 201, 400, 401, 403, 404, 500 상태 코드는 자주 사용되므로 기억하자!

Twitter Facebook LinkedIn

Kimsu