[Web] REST API에 대해

안녕하세요.

오늘은 REST API에 대해 알아보도록 하겠습니다.

 

REST?

REST는 REpresentational State Transfer의 약어로 네트워크 응용 프로그램을 디자인하는 아키텍처 스타일입니다. 기본적으로 REST는 클라이언트-서버 모델을 기반으로하며 클라이언트가 서버의 리소스에 액세스하거나 수정하기 위한 요청을 보냅니다. 이러한 리소스는 JSON 또는 XML과 같은 표준 데이터 형식을 사용하여 이해하기 쉽고 조작하기 쉬워집니다. REST를 활용한 API는 간결성, 확장 가능성 및 다양한 프로그래밍 언어 및 플랫폼과의 호환성 때문에 널리 사용되고 있습니다.

REST API?

REST API는 상태를 유지하지 않는 통신(Stateless)을 특징으로하며, 클라이언트의 각 요청은 서버가 이를 충족하기 위해 필요한 모든 정보를 포함합니다. 또한 REST API는 CRUD(Create, Read, Update, Delete) 작업을 수행하기 위해 GET, POST, PUT, DELETE와 같은 표준 HTTP 메소드를 활용합니다. 이러한 일관된 인터페이스는 클라이언트와 서버 간의 상호 작용을 단순화하고, 느슨하게 결합되고, 확장 가능하게 만듭니다.

REST API의 특징

단순하고 유연함
HTTP 메서드와 리소스 중심 접근 방식을 사용하여 이해하기 쉽고 다양한 어플리케이션에 적용 가능합니다.
확장성과 성능
Stateless 커뮤니케이션 덕분에 높은 확장성을 제공하며, 캐싱 등을 통해 성능을 향상시킬 수 있습니다.
플랫폼 독립성 및 상호 운용성
언어나 플랫폼에 구애받지 않고 다양한 환경에서 사용할 수 있으며, 다른 API와 쉽게 통합됩니다.

REST API 설계 원칙

리소스
API에서 제공하는 모든 데이터는 리소스로 간주됩니다. 각 리소스는 고유한 URI를 가집니다.
균일한 인터페이스
API는 모든 리소스에 대해 일관된 HTTP 메서드를 사용해야 합니다.
표현
API는 JSON, XML 등의 표준 포맷을 사용하여 데이터를 인코딩/디코딩해야 합니다.

URI?

URI(Uniform Resource Identifiers)는 REST API에서 노출된 리소스의 주소로 작동합니다. 이는 클라이언트가 특정 리소스를 고유하게 식별하고 액세스할 수 있는 수단을 제공합니다. 일반적으로 URI는 scheme, host, port, path, query parameter 및 fragment로 구성됩니다.

URI 주요 원칙

명확성
URI가 명확하고 이해하기 쉽게 설계되어 해당 리소스의 목적을 전달해야 합니다.
일관성
API 전체에서 URI 구조의 일관성을 유지하여 사용과 탐색의 편의성을 증진시킵니다.
간결성
URI를 간결하고 간결하게 유지하여 불필요한 복잡성이나 모호성을 피합니다.

URI 설계 규칙

리소스 중심 설계
URI는 동작이 아닌 API 내 리소스를 나타냅니다.  
동사가 아닌 명사 사용
URI는 리소스를 나타내므로 동사(예: /getUser, /createProduct) 대신 명사(예: /users, /products)를 사용해야 합니다.
동작을 위한 HTTP 메서드 활용
HTTP 메서드(GET, POST, PUT, DELETE)는 리소스에서 수행되는 동작을 정의합니다. 예를 들어 /users에 대한 GET 요청은 사용자 목록을 검색하고 /users에 대한 POST 요청은 새로운 사용자를 생성합니다.
단수 vs 복수
리소스 이름을 단수 명사 또는 복수 명사를 사용할지 결정해야 합니다. 두 접근 방식 모두 유효하지만, API 전반에서 일관성을 유지하는 것이 중요합니다.
기술적인 이름
리소스의 성격을 정확하게 반영하는 의미 있는 이름을 선택합니다. API 사용자를 혼동시킬 수 있는 암호화된 약어나 두문자어(각 단어의 머리글자만을 따서 만든 축약어의 일종)를 피합니다. 
계층 구조
리소스 중첩 관련된 리소스를 URI 내에서 중첩하여 표현하여 계층 관계를 나타냅니다. 그러나 지나치게 리소스를 중첩하지 않도록 주의해야 합니다.
깊이 제한
URI 계층의 깊이를 합리적으로 유지하여 과도한 중첩을 방지합니다. 깊이가 깊은 URI는 가독성을 저하시키고 API를 이해하고 사용하기 어렵게 만들 수 있습니다.
버전 관리
URI 경로에 버전 번호를 포함하거나 사용자 정의 헤더를 통해 API 버전을 관리하는 등 여러 가지 접근 방식이 있습니다. 

REST API 필수 구현 메서드

REST API는 리소스에 대한 다양한 동작을 수행하는 데 다양한 HTTP 메서드를 사용합니다.   

GET
보통 서버에서 데이터를 검색하고 데이터를 가져오는 데 사용됩니다. 
POST
새 리소스를 생성하기 위해 서버로 데이터를 보내는 데 사용됩니다. 
PUT
서버의 기존 리소스를 업데이트하는 데 사용됩니다. 
DELETE
서버에서 리소스를 제거하는 데 사용됩니다.

GET, POST, PUT, DELETE 메서드의 구현 예제

GET

fetch('/api/users')
  .then(response => response.json())
  .then(data => console.log(data));

POST

fetch("/api/users", {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		username: "poki",
		email: "poki@poki.tistory.com",
	}),
})
	.then(response => response.json())
	.then(data => console.log(data));

PUT

fetch("/api/users/1", {
	method: "PUT",
	headers: {
		"Content-Type": "application/json",
	},
	body: JSON.stringify({
		username: "poki_dev",
		email: "poki_dev@poki.tistory.com",
	}),
})
	.then(response => response.json())
	.then(data => console.log(data));

DELETE

fetch('/api/users/1', {
  method: 'DELETE'
})
  .then(response => console.log('사용자가 삭제되었습니다'));

 

REST API의 테스트와 디버깅

API 요청 전송 도구
Postman, curl 등을 사용하여 다양한 HTTP 요청을 보내고 응답을 확인합니다.
응답 검증 및 오류 처리
예상 데이터 형식 및 오류 코드와 일치하는지 확인하고, 명확한 에러 메시지 제공

REST API 구현 시 고려사항

페이징
대량의 데이터를 처리할 때, 페이지 번호 또는 오프셋을 사용하여 데이터를 작은 청크 단위로 가져옵니다.
필터링 및 정렬
클라이언트가 특정 조건에 맞는 데이터를 검색하고 정렬할 수 있도록 지원합니다.
HATEOAS (Hypermedia as the Engine of Application State)
API 응답에 링크를 포함하여 클라이언트가 관련된 자원과 사용 가능한 작업을 탐색할 수 있도록 지원합니다.
캐싱
클라이언트 및 서버 측에서 캐싱을 사용하여 성능을 향상시킵니다.
미디어 유형
JSON, XML, 이미지, 오디오, 비디오 등 다양한 데이터 형식을 지원합니다.
요청 제한
악용을 방지하고 공정한 접근을 보장하기 위해 요청 횟수를 제한합니다.

REST API 보안 

인증 및 권한 부여
사용자를 식별하고 자원에 대한 접근 권한을 제어합니다.
입력 유효성 검사
SQL 삽입 또는 XSS 공격과 같은 악성 코드 공격을 방지하기 위해 사용자 입력을 검사하고 정제합니다.
HTTPS 암호화
데이터 전송 중에 정보를 보호하기 위해 HTTPS를 사용합니다.
오류 처리 및 로깅
민감한 정보가 노출되지 않도록 오류 메시지를 설계하고 API 활동을 기록합니다.

REST API 설계 및 개발을 위한 도구

Swagger
API 설계 및 문서화를 위한 오픈 소스 도구
Postman
API 테스트 및 디버깅을 위한 도구

FAQ

REST API 개발 시 엄격한 RESTful 원칙을 따르는 것이 필수적인가요?

RESTful 원칙을 엄격히 준수하는 것은 권장되지만 모든 가이드라인을 엄격히 준수할 필요는 없습니다. 프로젝트의 요구 사항과 제한 사항에 따라 타협을 해야 할 수 있습니다. 그러나 REST의 핵심 원칙을 준수하는 것이 API의 일관성과 상호 운용성을 보장하는 데 도움이 됩니다.

자바스크립트 기반 REST API의 성능을 최적화하는 방법은 무엇인가요?

REST API의 성능을 최적화하기 위해 캐싱, 압축, 레이지 로딩 및 데이터베이스 인덱싱과 같은 기법을 구현할 수 있습니다. 네트워크 지연 시간을 최소화하기 위해 페이로드 크기를 줄이고 CDN을 활용하는 것도 중요합니다. 정기적인 모니터링과 프로파일링을 통해 성능 병목 현상을 식별하고 최적화할 수 있습니다.

 

결론

핵심 개념, 설계 원칙를 이해함으로써 개발자는 잘 구조화되고 안전하며 효율적인 REST API를 만들 수 있습니다. 또한 지속적인 문서화는 개발자가 API를 성공적으로 채택하는 데 중요한 역할을 할 것이며 효과적인 커뮤니케이션이 가능해질 것입니다. 

 

레퍼런스

REST API 튜토리얼

 

오타 혹은 잘못된 내용이 있다면 부담없이 댓글로 알려주세요 :)
문장을 다듬는데 ChatGPT의 도움을 받았습니다