С какими форматами работал по REST

Форматы данных в REST API

REST (Representational State Transfer) использует различные форматы для передачи данных. Как Java разработчик, работал с основными:

1. JSON (JavaScript Object Notation)

Самый популярный формат в 2025 году.

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.annotation.JsonProperty;

public class User {
    @JsonProperty("user_id")
    private int id;
    
    @JsonProperty("full_name")
    private String name;
    
    private String email;
}

// Сериализация: объект → JSON
ObjectMapper mapper = new ObjectMapper();
User user = new User(1, "John Doe", "john@example.com");
String json = mapper.writeValueAsString(user);
// {"user_id":1,"full_name":"John Doe","email":"john@example.com"}

// Десериализация: JSON → объект
String jsonString = "{\"user_id\":1,\"full_name\":\"John Doe\"}";
User parsedUser = mapper.readValue(jsonString, User.class);

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

• Лёгкий и читаемый
• Универсальная поддержка во всех языках
• Быстрый парсинг

Недостатки:

• Больше данных чем бинарные форматы
• Не поддерживает сложные типы (например, Date без преобразований)

2. XML (eXtensible Markup Language)

Использовался в SOAP, некоторые REST API.

import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlElement;
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;

@JacksonXmlRootElement(localName = "user")
public class UserXml {
    @JacksonXmlProperty
    private int id;
    
    @JacksonXmlProperty
    private String name;
}

// Jackson для XML
XmlMapper xmlMapper = new XmlMapper();
String xml = xmlMapper.writeValueAsString(user);
// <user><id>1</id><name>John Doe</name></user>

UserXml parsed = xmlMapper.readValue(xml, UserXml.class);

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

• Расширяемый
• Поддерживает валидацию через XSD
• Хорош для документов

Недостатки:

• Очень многословный
• Медленнее парсится чем JSON
• Редко используется в новых REST API

3. Protocol Buffers (protobuf)

Бинарный формат от Google, для высокопроизводительных систем.

// user.proto
syntax = "proto3";

message User {
    int32 id = 1;
    string name = 2;
    string email = 3;
}

import com.example.UserProto.User;

// Сериализация
User user = User.newBuilder()
    .setId(1)
    .setName("John Doe")
    .setEmail("john@example.com")
    .build();

byte[] serialized = user.toByteArray(); // Бинарные данные

// Десериализация
User parsed = User.parseFrom(serialized);

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

• Очень компактный (меньше данных)
• Быстрая сериализация/десериализация
• Строгая схема

Недостатки:

• Не человекочитаемый
• Требует генерации кода
• gRPC нужен для полноценного использования

4. Form Data (Application/x-www-form-urlencoded)

Для HTML форм и простых параметров.

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

@PostMapping("/login")
public ResponseEntity<?> login(
    @RequestParam String username,
    @RequestParam String password) {
    // username=john&password=secret
    return ResponseEntity.ok("Logged in");
}

Использование:

curl -X POST http://api.example.com/login \
  -d "username=john&password=secret"

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

• Простой
• Поддерживается везде
• Подходит для простых форм

Недостатки:

• Нет поддержки вложенных структур
• Не подходит для сложных объектов

5. Multipart/Form-Data

Для загрузки файлов.

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.multipart.MultipartFile;

@PostMapping("/upload")
public ResponseEntity<?> uploadFile(
    @RequestParam("file") MultipartFile file,
    @RequestParam("description") String description) {
    
    String filename = file.getOriginalFilename();
    long size = file.getSize();
    byte[] content = file.getBytes();
    
    // Сохраняем файл
    saveFile(filename, content);
    
    return ResponseEntity.ok("File uploaded");
}

Использование:

curl -X POST http://api.example.com/upload \
  -F "file=@photo.jpg" \
  -F "description=My photo"

6. GraphQL (квази-REST формат)

Альтернатива REST, более гибкая.

import graphql.GraphQL;
import graphql.schema.GraphQLSchema;

// GraphQL запрос
String query = """
    query {
        user(id: 1) {
            id
            name
            email
        }
    }
    """;

// GraphQL ответ — всё ещё JSON!
// {
//   "data": {
//     "user": {
//       "id": 1,
//       "name": "John Doe",
//       "email": "john@example.com"
//     }
//   }
// }

Сравнение форматов

┌──────────────┬──────────┬────────────┬─────────┬──────────┐
│ Формат       │ Размер   │ Скорость   │ Читаемо │ Сложность│
├──────────────┼──────────┼────────────┼─────────┼──────────┤
│ JSON         │ Средний   │ Быстро     │ Да      │ Низкая   │
│ XML          │ Большой  │ Медленно   │ Да      │ Средняя  │
│ Protobuf     │ Малый    │ Очень быстр│ Нет     │ Высокая  │
│ Form Data    │ Малый    │ Быстро     │ Да      │ Низкая   │
│ Multipart    │ Переменный│ Медленно   │ Нет     │ Средняя  │
└──────────────┴──────────┴────────────┴─────────┴──────────┘

Практический пример: REST контроллер с разными форматами

import org.springframework.web.bind.annotation.*;
import org.springframework.http.MediaType;

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    // JSON (по умолчанию в REST)
    @GetMapping("/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    public User getUserAsJson(@PathVariable int id) {
        return userService.findById(id);
    }
    
    // XML
    @GetMapping("/{id}", produces = MediaType.APPLICATION_XML_VALUE)
    public User getUserAsXml(@PathVariable int id) {
        return userService.findById(id);
    }
    
    // Принимаем JSON, возвращаем JSON
    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE,
                 produces = MediaType.APPLICATION_JSON_VALUE)
    public User createUser(@RequestBody User user) {
        return userService.save(user);
    }
}

Ключевые выводы

• JSON — стандарт де-факто для REST API в 2025
• XML — считается устаревшим, встречается в legacy системах
• Protobuf — для микросервисов и gRPC (высокопроизводительность)
• Form Data — для простых форм и параметров
• Multipart — для загрузки файлов
• Выбирай формат в зависимости от задачи — JSON для большинства случаев