RESTful web programming

[ParkYK]

RESTful이란?
REST(Representational State Transfer)는 웹의 장점을 최대한 활용할 수 있는 아키텍처로, 최근의 서버 프로그램은 다양한 브라우저와 모바일 디바이스에서도 통신을 할 수 있어야 한다. REST 아키텍처는 Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.

RESTFUL이란 REST의 원리를 따르는 시스템을 의미한다. 하지만 REST를 사용했다 하여 모두가 RESTful 한 것은 아니다.  REST API의 설계 규칙을 올바르게 지킨 시스템을 RESTful 하다고 할 수 있으며 모든 CRUD 기능을 POST로 처리 하는 API 혹은 URI 규칙을 올바르게 지키지 않은 API는, REST API의 설계 규칙을 올바르게 지키지 못한 시스템은 REST API를 사용하였지만 RESTful 하지 못한 시스템이 된다.

* REST의 특징 *

Uniform 인터페이스	URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일.
Stateless 무상태성	상태가 있다 없다는 의미는 사용자나 클라이언트의 컨택스트를 서버쪽에 유지 하지 않는다는 의미한다. 세션이나 쿠키 등을 별도로 관리하지 않기 때문에 API서버는 요청만을 들어오는 메시지로만 처리하기 때문에 구현이 단순하다. 무상태성을 유지한다. 서버는 각 클라이언트 요청을 독립적으로 처리하며, 이전 요청의 상태를 저장하지 않다.
Cacheable 캐시 가능	REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용한다. HTTP가 가진 캐싱 기능이 적용 가능하다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다. 적절한 캐시 제어 헤더를 사용하면 클라이언트와 중간 서버가 응답을 캐시하여 성능을 향상시킬 수 있다.
Self-descriptiveness 자가 서술적 메시지	REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다.
Client - Server Architecture	REST 서버는 API를 제공하고, 제공된 API를 이용해서 비즈니스 로직 처리 및 저장을 책임진다. 클라이언트의 경우 사용자 인증이나 컨택스트(세션, 로그인 정보) 등을 직접 관리하고 책임진다. 상호 간 의존성이 줄어들게 된다.
Hierarchical structure 계층화된 시스템, Layered System	클라이언트 입장에서는 REST ApI 서버만 호출한다. REST 서버는 다중 계층으로 구성될 수 있다. 예를 들어 보안, 로드 밸런싱, 암호화, 사용자 인증 등을 추가하여 구조상 유연성을 줄일 수 있다.

REST 구성
 - 자원(Resource) - HTTP URI

• RESTful 시스템에서는 모든 것이 자원이다. 자원은 URI(Uniform Resource Identifier)를 통해 식별된다.
• 예를 들어, 사용자의 정보를 얻으려면 /users라는 URI를 사용할 수 있다.
• 예 1: 사용자(User)
  • 자원 설명: 사용자 정보
  • URI 예시:
    • GET /users: 모든 사용자 목록을 가져온다.
    • GET /users/{id}: 특정 ID를 가진 사용자의 정보를 가져온다.
    • POST /users: 새로운 사용자를 생성한다.
    • PUT /users/{id}: 특정 ID를 가진 사용자의 정보를 업데이트한다.
    • DELETE /users/{id}: 특정 ID를 가진 사용자를 삭제한다.
  예 2: 블로그 게시물(Blog Post)
  • 자원 설명: 블로그 게시물
  • URI 예시:
    • GET /posts: 모든 블로그 게시물 목록을 가져온다.
    • GET /posts/{id}: 특정 ID를 가진 블로그 게시물의 정보를 가져온다.
    • POST /posts: 새로운 블로그 게시물을 생성한다.
    • PUT /posts/{id}: 특정 ID를 가진 블로그 게시물을 업데이트한다.
    • DELETE /posts/{id}: 특정 ID를 가진 블로그 게시물을 삭제한다.

 - 행위(Verb) - HTTP Method (GET, PUT, POST, DELETE 등)

 - 표현(Representations) - HTTP Message PayLoad( 전송되는 데이터 )

• 자원은 다양한 형식(예: JSON, XML, HTML 등)으로 표현될 수 있다.
• 클라이언트는 요청 헤더에서 원하는 표현 형식을 지정할 수 있다.
• 표현의 주요 개념
  1. • 자원은 여러 가지 형식으로 표현될 수 있다. 가장 일반적인 형식은 JSON(JavaScript Object Notation)과 XML(Extensible Markup Language)이다.
     • 예를 들어, 사용자 자원은 JSON 또는 XML 형식으로 표현될 수 있다.
  2. • 서버는 응답할 때 Content-Type 헤더를 사용하여 표현의 형식을 명시한다.
     • 예: Content-Type: application/json은 응답이 JSON 형식임을 나타낸다.
  3. • 클라이언트는 요청할 때 Accept 헤더를 사용하여 원하는 표현 형식을 지정할 수 있다.
     • 예: Accept: application/json은 클라이언트가 JSON 형식의 응답을 원함을 나타낸다.
  4. • 서버는 클라이언트의 요청에 따라 자원을 적절한 형식으로 변환하여 응답할 수 있다.
     • 자원 자체는 변하지 않지만, 표현 형식은 클라이언트의 요구에 맞게 변경다.

서버 응답: 클라이언트가 JSON 형식을 원할 때:
GET /users/123
Accept: application/json

서버 응답:
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 123,
    "name": "얼씨구",
    "email": "esg@example.com"
}

REST API 디자인 가이드
 - URI는 Resource를 표현해야 한다. 즉, URI가 리소스의 위치나 이름을 명확히 나타내야 한다. 이를 통해 클라이언트가 정확한 리소스에 접근하거나 해당 리소스를 식별할 수 있게 된다.
 - Resource에 대한 행위는 HTTP Method (GET, PUT, POST, DELETE 등)로 표현한다.

CRUD : Software가 가지는 기본적인 데이터 처리 기능을 통칭.
 - 생성(Create) : SQL - INSERT
 - 읽기(Read) : SQL - SELECT
 - 갱신(Update) : SQL - UPDATE
 - 삭제(Delete) : SQL - DELETE

URI 설계 시 주의할 점
 -  동사보다는 명사를 대문자 보다는 가급적 소문자를 사용하자. 아래 URL은 서로 다른 Resource의 표현이다.
    표현1) https://korea.com/Testing   -- X
    표현2) https://korea.com/test  -- O

 - 하이픈(-)은 URI 가독성을 높이는데 사용하자. Path에 띄어쓰기가 들어가는 경우 %20이 들어가 가독성이 떨어진다.
   하이픈(-)을 사용하여 띄어쓰기를 대체( _는 사용 X) 하고 가독성을 높일 수 있다.

    https://korea.com/test_a -- X

    https://korea.com/test-a -- O

    
 - 확장자를 사용하지 말자. REST API에서는 확장자를 사용하지 않으면서 Resource를 다루는 데 있어 더 유연해 진다.
   https://korea.com/mypic.jpg  -- X
   https://korea.com/mypic  -- O

- 마지막에 슬래시 (/)를 포함하지 않는다.
  https://korea.com/test/ -- X
  https://korea.com/test  -- O

- 행위를 포함하지 않는다.
  http://korea.com/delete-post/1 -- x
  http://korea.com/post/1 -- O

 * REST의 장점 : Open API를 제공하기 쉽다. Mashup이 활발해진 배경에는 REST의 영향을 무시할 수 없다. 멀티 플랫폼(Web, iOS, Android) 지원 및 연동이 용이하다. 원하는 타입(json, xml, rss…)으로 데이터를 주고 받을 수 있다. 기존 웹 인프라(HTTP)를 그대로 활용할 수 있다. (방화벽 문제에서 자유롭고, 로드 밸런서 등의 장비도 그대로 사용 가능하다). Resource가 Unique한 URI로 표현되도록 설계하면 웹 캐시 서버도 이용 가능하다.

* REST의 단점 : 사용할 수 있는 Method가 제한적이다. 즉, CRUD로 표현하기 모호한 작업을 처리하기 애매하며, HTTP 의존적이고 표준이 없어 관리가 어렵다.

REST API 디자인 가이드  https://bcho.tistory.com/914

Spring MVC 로 RESTFul 서비스 개발하기

https://devkingdom.tistory.com/108

html form 태그에서 PUT, DELETE 사용

https://jammdev.tistory.com/157

--------------RESTful 샘플 -------------------- 
🧑‍🦱 클라이언트 사이드에서 자바스크립트로 요청

let users = []; // 임시로 사용할 사용자 데이터

// 기본 라우트
app.get('/', (req, res) => {
  res.send('Welcome to the RESTful API!');
});

// 사용자 생성
app.post('/users', (req, res) => {
  const user = req.body;
  user.id = users.length + 1;   // 간단한 ID 생성 로직
  users.push(user);
  res.status(201).send(user);
});

// 모든 사용자 조회
app.get('/users', (req, res) => {
  res.send(users);
});

// 특정 사용자 조회
app.get('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id, 10);
  const user = users.find(u => u.id === userId);
  if (user) {
    res.send(user);
  } else {
    res.status(404).send({ message: 'User not found' });
  }
});

// 사용자 정보 수정
app.put('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id, 10);
  const userIndex = users.findIndex(u => u.id === userId);
  if (userIndex !== -1) {
    users[userIndex] = { ...users[userIndex], ...req.body };
    res.send(users[userIndex]);
  } else {
    res.status(404).send({ message: 'User not found' });
  }
});

// 사용자 삭제
app.delete('/users/:id', (req, res) => {
  const userId = parseInt(req.params.id, 10);
  const userIndex = users.findIndex(u => u.id === userId);
  if (userIndex !== -1) {
    users.splice(userIndex, 1);
    res.status(204).send();
  } else {
    res.status(404).send({ message: 'User not found' });
  }
});


------- 서버를 시작하고 API를 테스트 할 수 있다. --------
1) Node.js 서버인 경우 - express 모듈 사용
node index.js : 서버가 실행 중일 때, 다음과 같은 HTTP 요청을 사용하여 API를 테스트할 수 있다.

* 사용자 생성 (POST /users)
POST http://localhost:3000/users
Content-Type: application/json
{
  "name": "John",
  "email": "john@example.com"
}

* 모든 사용자 조회 (GET /users)
GET http://localhost:3000/users

* 특정 사용자 조회 (GET /users/ )
GET http://localhost:3000/users/1

* 사용자 정보 수정 (PUT /users/)
PUT http://localhost:3000/users/1
Content-Type: application/json
{
  "name": "John"
}

* 사용자 삭제 (DELETE /users/)
DELETE http://localhost:3000/users/1


2) ApachTomcat 서버인 경우 - Spring  사용
@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;

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

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

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        Optional<User> user = userService.getUserById(id);
        if (user.isPresent()) {
            return ResponseEntity.ok(user.get());
        } else {
            return ResponseEntity.notFound().build();
        }
    }

    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        User updatedUser = userService.updateUser(id, userDetails);
        return ResponseEntity.ok(updatedUser);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}