S01L02 - 리소스 기반 URI

html

Resource-Based URIs: 종합 안내서

목차

소개
Resource-Based URIs 이해
Action-Based URIs 대 Resource-Based URIs
효과적인 Resource-Based URIs 설계
Resource-Based URIs의 HTTP 메서드
HTTP 상태 코드 설명
Resource-Based URIs 구현: 실용적인 예제
최고의 실천 방안 및 관행
결론


소개
웹 개발 및 API 디자인 분야에서 Uniform Resource Identifiers (URIs)는 리소스에 어떻게 접근하고 조작할지를 정의하는데 중요한 역할을 합니다. 이 전자책은 직관적이고 확장 가능하며 유지 관리가 쉬운 RESTful APIs를 만드는 데 있어 기본 개념인 Resource-Based URIs를 깊이 있게 다룹니다.
Resource-Based URIs를 이해하는 것은 개발자들이 최고의 실천 방안에 부합하는 APIs를 디자인하는 데 필수적이며, 클라이언트와 서버 간의 통신에서 명확성과 효율성을 보장합니다. 이 가이드는 Action-Based URIs와 Resource-Based URIs 간의 차이점, HTTP 메서드의 중요성, 상태 코드를 탐구하고 이해를 공고히 하기 위한 실용적인 예제를 제공합니다.
Resource-Based URIs의 장단점
장점:

명확성: Resource를 중심으로 URIs를 구조화함으로써 가독성과 이해도를 향상시킵니다.
확장성: API의 확장과 유지 관리를 용이하게 합니다.
일관성: 다양한 엔드포인트 간의 일관성을 촉진하여 API를 더 예측 가능하게 만듭니다.

단점:

초기 복잡성: REST 원칙에 대한 더 깊은 이해가 필요할 수 있습니다.
경직성: 엄격한 준수는 특정 상황에서 유연성을 제한할 수 있습니다.

비교 개요



특징
Action-Based URIs
Resource-Based URIs




구조
동작을 나타내는 동사를 사용합니다 (예: /getBrands)
리소스를 중심으로 배치됩니다 (예: /brands)


가독성
다양한 동작 용어로 인해 혼란스러울 수 있습니다.
리소스 계층 구조를 중심으로 더 직관적이고 조직적입니다.


REST 준수
REST 원칙과 덜 일치합니다.
REST 표준을 완전히 준수합니다.


확장성
API가 성장함에 따라 번거로워질 수 있습니다.
명확한 리소스 관리로 쉽게 확장 가능합니다.




1장: Resource-Based URIs 이해
Resource-Based URIs란 무엇인가?
Resource-Based URIs는 애플리케이션 또는 서비스 내의 특정 리소스를 나타내는 엔드포인트입니다. 동작이나 작업에 집중하는 대신, 이러한 URIs는 쇼룸 맥락에서 brands, bikes, spares와 같은 그들이 나타내는 엔티티를 중심으로 구조화됩니다.
Resource-Based URIs의 중요성
Resource-Based URIs를 채택하면 API 디자인이 RESTful 원칙에 맞춰지면서 확장성, 유지 관리성 및 명확성을 촉진합니다. 이 접근 방식은 리소스에 접근하고 조작하는 명확하고 일관된 방법을 제공하여 클라이언트와 서버 간의 상호 작용을 단순화합니다.
Resource-Based URIs을 언제 그리고 어디에 사용할 것인가
Resource-Based URIs는 다음에 이상적입니다:

RESTful APIs: REST 표준을 준수하도록 보장합니다.
Microservices Architecture: 모듈식이고 확장 가능한 서비스 설계를 용이하게 합니다.
Any API Design: 명확성과 유지 관리가 우선인 경우.


2장: Action-Based URIs 대 Resource-Based URIs
Action-Based URIs
Action-Based URIs는 특정 동작이나 작업을 나타내는 동사를 포함합니다. 예를 들어:

/getBrands
/setBikes
/deleteSpare?id=25

이 접근 방식은 작동할 수 있지만, 종종 혼란과 일관성 결여로 이어집니다, 특히 API가 성장할수록.
Resource-Based URIs
Resource-Based URIs는 관련된 엔티티에 초점을 맞춥니다:

/brands
/brands/bajaj
/bikes/honda

이 구조는 가독성을 향상시키고 RESTful 최고의 실천 방안과 일치시킵니다.
비교 분석



측면
Action-Based URIs
Resource-Based URIs




동사 사용
동작 동사(get, set)를 포함합니다.
리소스를 나타내는 명사를 사용합니다.


명확성
덜 직관적입니다.
더 직관적이고 조직적입니다.


REST 준수
REST 원칙과 덜 일치합니다.
REST 표준을 완전히 준수합니다.


유지 관리
번거로워질 수 있습니다.
유지 관리 및 확장이 용이합니다.




3장: 효과적인 Resource-Based URIs 설계
URI 구조화
효과적인 Resource-Based URIs는 리소스 간의 관계를 나타내는 계층적 구조를 따릅니다. 예를 들어:

/brands – 모든 brands에 접근.
/brands/bajaj – 특정 brand, Bajaj에 접근.
/bikes/honda – Honda brand 하의 모든 bikes에 접근.
/spares/suzuki – Suzuki 관련 spares에 접근.
/spares/25 – ID로 특정 spare part에 접근.

최고의 실천 방안

복수 명사 사용: 컬렉션을 복수 형태로 나타냅니다 (예: /brands).
계층 구조 표현: URI 구조를 통해 리소스 간의 관계를 반영합니다.
일관된 명명 규칙: 예측 가능성을 위해 URI 명명에서 일관성을 유지합니다.

실용적인 예제
쇼룸 API에서는 다양한 brands, 그들의 bikes, 그리고 spare parts에 접근할 수 있다고 가정해 봅시다. 잘 설계된 Resource-Based URI 구조는 다음과 같을 수 있습니다:




		
		
			
			
Java
			
			/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
			
				
					
				
					1
2
3
4
5
6
7
				
						/brands
/brands/bajaj
/bikes
/bikes/honda
/spares
/spares/suzuki
/spares/25
					
				
			
		



4장: Resource-Based URIs의 HTTP 메서드
HTTP 메서드 개요
HTTP 메서드는 리소스에서 수행할 수 있는 동작을 정의합니다. RESTful APIs에서 가장 일반적으로 사용되는 메서드는 다음과 같습니다:

GET: 정보를 조회합니다.
POST: 새 리소스를 생성합니다.
PUT: 기존 리소스를 업데이트합니다.
DELETE: 리소스를 삭제합니다.

상세 설명

GET: 리소스에서 데이터를 조회하는 데 사용됩니다. 예를 들어, GET /brands는 모든 brands를 조회합니다.
POST: 새로운 리소스를 생성하는 데 사용됩니다. 예를 들어, POST /brands는 새로운 brand를 추가합니다.
PUT: 기존 리소스를 업데이트하는 데 사용됩니다. 예를 들어, PUT /brands/bajaj는 Bajaj brand 정보를 업데이트합니다.
DELETE: 리소스를 삭제하는 데 사용됩니다. 예를 들어, DELETE /spares/25는 ID 25의 spare part를 삭제합니다.

메서드와 작업 매핑



HTTP 메서드
작업
예제 URI




GET
리소스(들)를 조회합니다.
/brands


POST
새로운 리소스를 생성합니다.
/brands


PUT
기존 리소스를 업데이트합니다.
/brands/bajaj


DELETE
리소스를 삭제합니다.
/spares/25




5장: HTTP 상태 코드 설명
상태 코드의 중요성
HTTP 상태 코드는 클라이언트의 요청 결과를 서버에 전달합니다. 작업이 성공했는지 아니면 오류가 발생했는지에 대한 필수 피드백을 제공합니다.
일반적인 상태 코드

200 OK: 요청이 성공적으로 처리되었습니다.
201 Created: 새로운 리소스가 성공적으로 생성되었습니다.
404 Not Found: 요청한 리소스가 존재하지 않습니다.
500 Internal Server Error: 서버에서 일반적인 오류가 발생했습니다.

상태 코드 분류



카테고리
코드 범위
설명




1xx
100-199
정보 제공 응답


2xx
200-299
성공적인 응답


3xx
300-399
리디렉션 메시지


4xx
400-499
클라이언트 오류 응답


5xx
500-599
서버 오류 응답



실용적인 사용
클라이언트가 GET /brands에 요청을 보내면, 성공적인 조회는 200 OK 상태를 반환합니다. 존재하지 않는 spare part에 GET /spares/999를 사용하여 접근하려고 시도하면, 404 Not Found 상태가 발생합니다.

6장: Resource-Based URIs 구현: 실용적인 예제
시나리오: Showroom API
brands, bikes, spare parts를 관리하는 쇼룸을 고려해 봅시다. 이 엔티티들을 처리하기 위해 Resource-Based URIs를 구현할 것입니다.
예제 URI
Brands:

GET /brands – 모든 brands를 조회합니다.
GET /brands/bajaj – Bajaj에 대한 정보를 조회합니다.
POST /brands – 새로운 brand를 추가합니다.
PUT /brands/bajaj – Bajaj의 정보를 업데이트합니다.
DELETE /brands/bajaj – 시스템에서 Bajaj를 제거합니다.

Bikes:

GET /bikes – 모든 bikes를 조회합니다.
GET /bikes/honda – Honda의 bikes를 조회합니다.
POST /bikes – 새로운 bike를 추가합니다.
PUT /bikes/honda – Honda bikes 정보를 업데이트합니다.
DELETE /bikes/honda – Honda bikes를 제거합니다.

Spares:

GET /spares – 모든 spare parts를 조회합니다.
GET /spares/suzuki – Suzuki의 spare parts를 조회합니다.
GET /spares/25 – ID 25의 spare part를 조회합니다.
POST /spares – 새로운 spare part를 추가합니다.
PUT /spares/25 – ID 25의 spare part를 업데이트합니다.
DELETE /spares/25 – ID 25의 spare part를 제거합니다.

예제 코드 구현
아래는 Node.js과 Express를 사용하여 brands를 관리하기 위한 Resource-Based URIs를 구현하는 간단한 예제입니다.




		
		
			
			
Java
			
			const express = require('express');
const app = express();
app.use(express.json());

let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];

// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});

// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});

// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});

// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});

// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
				
						const express = require('express');
const app = express();
app.use(express.json());
 
let brands = [
  { id: 1, name: 'Bajaj' },
  { id: 2, name: 'Honda' },
];
 
// Get all brands
app.get('/brands', (req, res) => {
  res.status(200).json(brands);
});
 
// Get a specific brand
app.get('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  res.status(200).json(brand);
});
 
// Add a new brand
app.post('/brands', (req, res) => {
  const newBrand = {
    id: brands.length + 1,
    name: req.body.name,
  };
  brands.push(newBrand);
  res.status(201).json(newBrand);
});
 
// Update a brand
app.put('/brands/:name', (req, res) => {
  const brand = brands.find(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (!brand) return res.status(404).send('Brand not found');
  brand.name = req.body.name;
  res.status(200).json(brand);
});
 
// Delete a brand
app.delete('/brands/:name', (req, res) => {
  const brandIndex = brands.findIndex(b => b.name.toLowerCase() === req.params.name.toLowerCase());
  if (brandIndex === -1) return res.status(404).send('Brand not found');
  const deletedBrand = brands.splice(brandIndex, 1);
  res.status(200).json(deletedBrand);
});
 
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
					
				
			
		


코드 설명

설정: Express 애플리케이션을 초기화하고 샘플 brands 배열을 정의합니다.
GET /brands: 모든 brands 목록을 조회하여 200 OK 상태로 응답합니다.
GET /brands/:name: 이름으로 특정 brand를 조회합니다. 찾을 수 없으면 404 Not Found를 반환합니다.
POST /brands: 컬렉션에 새로운 brand를 추가하고 201 Created 상태로 응답합니다.
PUT /brands/:name: 기존 brand의 이름을 업데이트합니다. brand가 존재하지 않으면 404 Not Found를 반환합니다.
DELETE /brands/:name: 컬렉션에서 brand를 제거합니다. brand를 찾을 수 없으면 404 Not Found를 반환합니다.

출력 예제
요청: GET /brands
응답:




		
		
			
			
Java
			
			[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
			
				
					
				
					1
2
3
4
				
						[
  { "id": 1, "name": "Bajaj" },
  { "id": 2, "name": "Honda" }
]
					
				
			
		



7장: 최고의 실천 방안 및 관행
일관된 명명
컬렉션을 나타내기 위해 리소스 이름에 복수 명사를 사용합니다. 예를 들어, /brands를 /brand 대신 사용합니다.
계층적 구조화
URI 구조를 통해 리소스 간의 관계를 반영합니다. 중첩된 리소스는 계층 구조를 논리적으로 나타내야 합니다.
HTTP 메서드 사용
RESTful 원칙을 준수하면서 리소스에 대한 작업을 수행하기 위해 적절한 HTTP 메서드를 활용합니다.
버전 관리
URI에 버전 관리를 구현하여 기존 클라이언트를 방해하지 않고 시간에 따라 변화를 관리합니다. 예를 들어:




		
		
			
			
Java
			
			/v1/brands
/v2/brands
			
				
					
				
					1
2
				
						/v1/brands
/v2/brands
					
				
			
		


오류 처리
클라이언트가 요청의 결과를 이해할 수 있도록 의미 있는 오류 메시지와 적절한 HTTP 상태 코드를 제공합니다.
문서화
사용 가능한 엔드포인트, 메서드, 매개변수 및 예상 응답을 상세히 설명하는 API의 포괄적인 문서를 유지 관리합니다.

결론
Resource-based URIs는 RESTful API 디자인의 초석으로, 리소스를 관리하는 구조적이고 직관적인 접근 방식을 제공합니다. 동작보다 엔티티에 초점을 맞춤으로써, 개발자들은 확장 가능하고 유지 관리가 용이하며 클라이언트가 쉽게 이해할 수 있는 APIs를 만들 수 있습니다.
URI 설계에서 최고의 실천 방안, 적절한 HTTP 메서드 사용, 효과적인 오류 처리를 채택함으로써 API가 현재 요구 사항을 충족할 뿐만 아니라 미래의 필요에도 적응할 수 있도록 보장합니다. 간단한 애플리케이션을 구축하든 복잡한 microservices 아키텍처를 구축하든, Resource-Based URIs는 강력하고 효율적인 API 개발을 위한 기반을 제공합니다.
참고: 이 기사는 AI가 생성했습니다.
HTTP 메서드	작업	예제 URI
GET	리소스(들)를 조회합니다.	/brands
POST	새로운 리소스를 생성합니다.	/brands
PUT	기존 리소스를 업데이트합니다.	/brands/bajaj
DELETE	리소스를 삭제합니다.	/spares/25
특징	Action-Based URIs	Resource-Based URIs
구조	동작을 나타내는 동사를 사용합니다 (예: /getBrands)	리소스를 중심으로 배치됩니다 (예: /brands)
가독성	다양한 동작 용어로 인해 혼란스러울 수 있습니다.	리소스 계층 구조를 중심으로 더 직관적이고 조직적입니다.
REST 준수	REST 원칙과 덜 일치합니다.	REST 표준을 완전히 준수합니다.
확장성	API가 성장함에 따라 번거로워질 수 있습니다.	명확한 리소스 관리로 쉽게 확장 가능합니다.
측면	Action-Based URIs	Resource-Based URIs
동사 사용	동작 동사(get, set)를 포함합니다.	리소스를 나타내는 명사를 사용합니다.
명확성	덜 직관적입니다.	더 직관적이고 조직적입니다.
REST 준수	REST 원칙과 덜 일치합니다.	REST 표준을 완전히 준수합니다.
유지 관리	번거로워질 수 있습니다.	유지 관리 및 확장이 용이합니다.
카테고리	코드 범위	설명
1xx	100-199	정보 제공 응답
2xx	200-299	성공적인 응답
3xx	300-399	리디렉션 메시지
4xx	400-499	클라이언트 오류 응답
5xx	500-599	서버 오류 응답