В каком виде можно передать эндпоинт

Форматы передачи эндпоинтов API

Эндпоинт - это точка доступа в API, которая определяет URL ресурса и метод HTTP для выполнения операции. Эндпоинты можно передавать и документировать в различных форматах в зависимости от контекста и целей.

REST API (основной формат)

Базовый формат - REST эндпоинты описываются через HTTP метод и путь:

МЕТОД URL
GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/{id}
PUT /api/v1/users/{id}
DELETE /api/v1/users/{id}

Это стандартный способ, использующий глаголы HTTP (GET, POST, PUT, DELETE, PATCH) и существительные во множественном числе для ресурсов.

OpenAPI/Swagger

YAML формат - специализированный формат для описания API. Популярен благодаря инструментам типа Swagger UI, которые генерируют интерактивную документацию:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
paths:
  /api/v1/users:
    get:
      summary: Получить всех пользователей
      responses:
        200:
          description: Список пользователей
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: #/components/schemas/User
    post:
      summary: Создать пользователя
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: #/components/schemas/User

JSON формат - альтернативный формат OpenAPI, менее компактный, но более универсальный:

{
  "openapi": "3.0.0",
  "paths": {
    "/api/v1/users": {
      "get": {
        "summary": "Получить пользователей"
      }
    }
  }
}

GraphQL

GraphQL запросы - альтернативная парадигма вместо REST, где фронтенд явно запрашивает только нужные поля:

query {
  users {
    id
    name
    email
  }
}

mutation {
  createUser(input: {name: "John", email: "john@example.com"}) {
    id
    name
  }
}

Schema определение - GraphQL требует определения schema с типами:

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  users: [User!]!
  user(id: ID!): User
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

gRPC

Protobuf формат - для высокопроизводительного API с бинарной сериализацией:

service UserService {
  rpc GetUsers (Empty) returns (UserList);
  rpc CreateUser (User) returns (User);
  rpc UpdateUser (User) returns (User);
  rpc DeleteUser (UserId) returns (Empty);
}

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

SOAP/XML

WSDL описание - старый стандарт, все еще используется в корпоративных системах:

<wsdl:operation name="GetUser">
  <wsdl:input message="tns:GetUserRequest"/>
  <wsdl:output message="tns:GetUserResponse"/>
</wsdl:operation>

Документация в Markdown

Простой текстовый формат для документации:

## Get Users

**Endpoint:** `GET /api/v1/users`

**Description:** Получает список всех пользователей

**Parameters:**
- `limit` (query, integer) - максимальное количество результатов
- `offset` (query, integer) - смещение от начала

**Response:**
```json
[
  {"id": 1, "name": "John"}

]

Status Codes:

• 200 OK
• 400 Bad Request
• 401 Unauthorized

### Постман Collection

**JSON формат для инструмента Postman** - удобен для тестирования:

```json
{
  "info": {"name": "User API"},
  "item": [
    {
      "name": "Get Users",
      "request": {
        "method": "GET",
        "url": "{{base_url}}/api/v1/users"
      }
    }
  ]
}

URL параметры и примеры

Query параметры - передаются в строке запроса:

GET /api/v1/users?limit=10&offset=20

Path параметры - часть самого пути:

GET /api/v1/users/{id}
GET /api/v1/users/123

Request Body - для POST/PUT запросов:

POST /api/v1/users
Content-Type: application/json

{"name": "John", "email": "john@example.com"}

Headers - метаданные запроса:

GET /api/v1/users
Authorization: Bearer token123
Content-Type: application/json
X-Custom-Header: value

Лучшие практики

Версионирование - включайте версию в URL (/api/v1/, /api/v2/) для обратной совместимости.

Konsistency - используйте одинаковый формат для всех эндпоинтов одного API.

Документация - всегда документируйте эндпоинты с примерами, параметрами и кодами ответов.

Примеры в документации - предоставляйте полные примеры curl, JavaScript, Python для облегчения интеграции.

Выбор формата зависит от типа API, требований клиентов и предпочтений команды разработки. REST с OpenAPI остается наиболее распространенной комбинацией в 2025 году благодаря простоте и широкой поддержке инструментов.