REST API

7/15/2025

이 본문 내용은 아래 링크의 영상 내용을 기반으로 만들었습니다. 긴 글이 싫다면 영상이 설명을 잘 해주시니 꼭 보길 바란다.

사실 작성일로 부터 얼마전에 면접 질문으로 REST API 는 뭔가요? 라는 질문을 받았었는데, 당연하다는 듯이 HTTP 내용에 대해 설명했던 기억이 있다. 그래서 HTTP method 를 설명하고, 각 메소드 특징 등을 설명하고 했었는데, 지금 영상을 보고 나니 포인트가 벗어난 설명을 한게 아닌가 라는 생각이 든다.

REST API 란?

간결하게 설명하면 영상대로 API 주소 규칙이다. 프론트 - 백엔드, 클라이언트와 - 서버가 서로 요청/응답으로 대화를 할 때, 이 대화에 규칙을 주는 것이 바로 REST API 이다.

진짜 REST 의 스펙

이건 진짜 영상 보기 전에 몰랐던 내용인데, 이 REST API 를 개발한 개발자, Roy Fielding 이라는 분은 처음에 REST API 형식에 대해 창시했을 때 우리가 현재 사용하고 있는 이런 형식을 얘기한 적이 없다고 한다.

현재 일반적으로 많이 사용하는 형식은 보통 HTTP method 와 주소값을 결합한 형태로, GET /movies 이렇게 주소를 만들면 movie 들의 조회 역할을 부여하고, POST /movies 이렇게 주소를 만들면 새로운 movie 를 만드는 형식일 것이다.

하지만 REST 창시자인 Roy Fielding 개발자의 REST 컨셉에는 이런 HTTP method 의 스펙은 포함되어있지 않고, 오히려 프로토콜에 자유로워야 한다고 한다.

또한 우리가 API 요청에 대해 이런 규칙에 맞춰서 URL 을 하드코딩하거나, API 문서를 만들거나 하는 작업들이 있기 마련인데, REST API 의 실제 의도 대로라면 프론트(클라이언트) 에서 개발하는데에 이런 문서는 필요가 없어야 한다.

그럼 어떻게 이게 가능할까? 라는 의문이 들텐데, 일단 URL 을 하드코딩 하던 부분에 대해 REST 의 컨셉을 따라가 보면, 클라이언트(프론트) 는 이 주소들을 가지고 있는 시작점 되는 주소만 알고 있고, 이 시작점 되는 주소를 조회하면, 나머지 데이터 접근을 위한 주소들을 반환해주는 것이다.

예시로 보면 GET /api/users/123 이런 요청을 통해,

{
	...
	"_links": {
		"self": {
			"href": "/api/users/123",
			"method": "GET"
		},
		"orders": {
			"href": "/api/users/123/orders",
			"method": "GET"
			"title": "주문 목록 보기"
		},
		...
	}
	...
}

이런 응답을 받아서, _links 에 있는 주소를 통해 다른 API 요청을 사용해야 한다는 것이다.

이렇게 개발하게 되면, 백엔드는 어떤 주소가 변경되던 간에 저 시작점에 주어지는 주소만 변경해주면, 프론트는 저 응답값(DTO) 에 있는 특정 변수만 사용하기 때문에 코드 변경없이 운영이 가능해진다.

이렇게 개발하는 방식에 대해 HATEOAS(Hypermedia as the Engine of Application State) 라고 한다.

그리고 하나 더, 서버에서 주는 데이터를 프론트에 그대로 노출하면 안된다 라는 부분이 있다. (🤔 내용상 (DB)서버에서 오는 원 데이터를 그대로 프론트에 전달하지 말라는 의미로 보인다) 실제 뒤에서 관리하는 데이터에 대해서 프론트에 그대로 노출하는, DB 스키마를 그대로 노출하지말고, 실제 가져다 사용하는 곳에 유의미한 내용들만, 유의미한 내용이 되도록 DTO 등을 통해 관리되어야 한다는 것이다. (이 부분은 백엔드에서도 자주 논의 되는 내용이라 개인적으로 최근 개발에는 잘 적용하고 있다) 또한 이 요청에 응답으로 추가 요청할 필요없도록 연관된 데이터도 같이 전달하고, 위의 HATEOAS 를 적용한 링크까지 전달해주는게 실제 REST 컨셉에 맞는 개발이라 볼 수 있다.

즉 이런 내용들을 종합하여 정리하면, 프론트(클라이언트) 개발에서 API 문서가 없어도 개발할 수 있고, 백엔드 수정에 영향을 받지 않고 개발할 수 있는 방식을 REST API 라고 할 수 있다.

  • HATEOAS 방식을 통해 시작점 주소를 알면 연관된 주소는 응답값의 변수로 사용할 수 있도록 개발해야 한다.
  • 응답값에 대해 의미있는 명칭을 사용하여 API 문서화가 있지 않으면 알 수 없는 개발이 아닌, API 목적만 알더라도 개발 가능하고 영향없는 DTO 를 사용하여 개발되어야 한다.

    • 이 두 가지가 REST 방식 개발의 핵심이라고 볼 수 있다.

    실제 실무에서 사용할 수 있을까?

    영상의 내용대로 실제 개발에서 모두 잘 사용할 수 있느냐는 의문이긴하다. HATEOAS 방식은 정말 대부분의 API 응답에 대해서 연관한 link 들이 추가되어야 하고, 당연히 프론트는 이런 링크들이 잘 오는지 체크를 해주어야한다. 개인적인 의견으로 정말 대기업의, 구조가 탄탄한 IT 조직이라면 고려해 볼 수 있을 것 같다고 생각한다.

    그럼 두번째 의미 있는 응답값에 대해서는 어느 정도 적용의 여지가 있지 않을까 생각된다. 실제로 이전 프로젝트에서 DB 구조(Entity)를 그대로 노출하는 경우가 있었는데, 이런 부분들에 대해 팀내 공유하며 실제 Entity 모델을 그대로 노출하지말고 응답값이 되는 DTO(비즈니스 모델)을 사용하여 응답하고, 응답값에 대해 어떤 값인지 확인하지 않도록 status 등의 값은 enum 의 의미있는 값을 통해 전달하자고 한적이 있다.

    Entity 를 노출하지 말자는 내용은 컬럼의 변경이 있거나, ORM 등을 사용할 때 변경 사항이 API 사용하는 프론트까지 번지지 않도록 막는 역할로서도 의미가 있다고 생각하였고, 의미있는 응답값을 사용하다 보면 당시 관리하던 API 문서의 관리 포인트가 서서히 줄어들 것이고, 프론트도 신규 기능 개발에 대해 실제 API 스펙이 나오는 것과 별개로 개인적인 추측하에 개발을 진행할 수 있다는 측면이 있을거라 생각했다.

    하여 개인의견으로 첫번째 HATEOAS 방식은 무리가 있더라도, 두번째 의미있는 명칭과 데이터를 제공하는 부분은 적용해보면 좋을 것 같다.