Что такое RESTful сервис?

Что такое RESTful сервис

REST (Representational State Transfer) — это архитектурный стиль для проектирования распределённых систем. RESTful сервис — это веб-сервис, который следует принципам REST.

Ключевые принципы REST

1. Ресурсы и их представления

Всё в REST — это ресурсы. Каждый ресурс имеет URL (URI), и клиент работает с представлениями этих ресурсов (обычно JSON или XML).

// Ресурс: User с ID 123
// URL: /api/users/123
// Представление (JSON):
// { "id": 123, "name": "John", "email": "john@example.com" }

2. Стандартные HTTP методы (CRUD)

GET    /api/users        // Получить список всех пользователей
GET    /api/users/123    // Получить пользователя с ID 123
POST   /api/users        // Создать нового пользователя
PUT    /api/users/123    // Полностью обновить пользователя 123
PATCH  /api/users/123    // Частично обновить пользователя 123
DELETE /api/users/123    // Удалить пользователя 123

3. Stateless (Без состояния)

Каждый запрос содержит всю информацию, необходимую серверу. Сервер не хранит контекст сессии между запросами.

// Каждый запрос независим
GET /api/users/123 HTTP/1.1
Authorization: Bearer token123
Host: api.example.com

4. Кэшируемость

Ответы должны определять свою кэшируемость, используя HTTP заголовки.

Cache-Control: max-age=3600  // Кэшировать на 1 час
ETag: "12345"               // Уникальный идентификатор версии

Пример RESTful сервиса на Spring Boot

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    public List<User> getAllUsers() {
        // GET /api/users
        return userService.findAll();
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // GET /api/users/123
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
    
    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // POST /api/users
        User created = userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
        // PUT /api/users/123
        return ResponseEntity.ok(userService.update(id, user));
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        // DELETE /api/users/123
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

Преимущества RESTful

• Простота: использует стандартные HTTP методы
• Масштабируемость: stateless архитектура
• Универсальность: работает с любым клиентом (веб, мобиль, ПК)
• Кэширование: встроенная поддержка HTTP кэша
• Гибкость: легко версионировать (v1, v2)

HTTP статус коды

правильный RESTful сервис использует правильные статус коды:

• 200 — OK (успешно)
• 201 — Created (ресурс создан)
• 204 — No Content (успешно, нет содержимого)
• 400 — Bad Request (ошибка клиента)
• 401 — Unauthorized (требуется аутентификация)
• 403 — Forbidden (доступ запрещён)
• 404 — Not Found (ресурс не найден)
• 500 — Internal Server Error (ошибка сервера)

RESTful подход — это не просто создание API, это философия проектирования, где всё основано на стандартах HTTP и семантике веб-протокола.