Что такое ссылка на API?

Что такое ссылка на API?

Ссылка на API (API reference) — это полная техническая документация, которая описывает все доступные методы, функции и endpoints какого-либо API, включая параметры, типы возвращаемых значений, примеры использования и ограничения. Это справочник разработчика.

Что включает ссылка на API?

1. Endpoints (конечные точки)

Для REST API — это адреса, по которым можно обращаться:

GET  /api/v1/users           — получить всех пользователей
GET  /api/v1/users/{id}      — получить пользователя по ID
POST /api/v1/users           — создать нового пользователя
PUT  /api/v1/users/{id}      — обновить пользователя
DELETE /api/v1/users/{id}    — удалить пользователя

2. Методы HTTP

Какой HTTP метод использовать:

GET     — получить данные
POST    — создать данные
PUT     — обновить данные
PATCH   — частичное обновление
DELETE  — удалить данные
HEAD    — получить заголовки
OPTIONS — доступные методы

3. Параметры (parameters)

Что нужно передать с запросом:

// Параметры пути (path parameters)
GET /api/users/{id}

// Параметры запроса (query parameters)
GET /api/users?page=1&limit=10&sort=name

// Заголовки (headers)
Authorization: Bearer token123
Content-Type: application/json

// Тело запроса (request body)
POST /api/users
{
  "name": "John",
  "email": "john@example.com"
}

4. Типы и структуры данных

Какие данные возвращает API:

interface User {
  id: string;           // UUID
  name: string;         // текст
  email: string;        // email
  age?: number;         // опциональное число
  createdAt: Date;      // дата
  isActive: boolean;    // флаг
  roles: string[];      // массив
}

interface ApiResponse<T> {
  status: 'success' | 'error';
  data?: T;
  error?: string;
}

5. HTTP коды ответов (status codes)

Что означает каждый код:

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

6. Примеры запросов и ответов

Конкретные примеры использования:

// Пример 1: Получить пользователя
GET /api/v1/users/123

Ответ 200:
{
  "status": "success",
  "data": {
    "id": "123",
    "name": "John",
    "email": "john@example.com",
    "createdAt": "2023-01-15T10:30:00Z"
  }
}

// Пример 2: Создать пользователя
POST /api/v1/users
Content-Type: application/json

{
  "name": "Jane",
  "email": "jane@example.com",
  "age": 28
}

Ответ 201:
{
  "status": "success",
  "data": {
    "id": "456",
    "name": "Jane",
    "email": "jane@example.com",
    "age": 28,
    "createdAt": "2023-01-20T15:45:00Z"
  }
}

// Пример 3: Ошибка
GET /api/v1/users/999

Ответ 404:
{
  "status": "error",
  "error": "User not found"
}

Примеры реальных API References

1. Документация GitHub API

https://docs.github.com/en/rest

Описывает:
- GET /repos/{owner}/{repo}/issues
- POST /repos/{owner}/{repo}/issues
- GET /repos/{owner}/{repo}/issues/{issue_number}
и т.д.

2. Документация Twitter API

https://developer.twitter.com/en/docs/twitter-api

Описывает методы для работы с твитами, пользователями и т.д.

3. Документация Stripe API (платежи)

https://stripe.com/docs/api

Описывает методы для работы с платежами, подписками и т.д.

Как использовать ссылку на API?

Шаг 1: Найти нужный endpoint

Цель: Получить список всех заказов пользователя

Ищу в документации → Orders → List User Orders
Нахожу: GET /api/v1/users/{userId}/orders

Шаг 2: Посмотреть параметры

Параметры пути:
- userId (required, string) — ID пользователя

Параметры запроса:
- page (optional, integer) — номер страницы (по умолчанию 1)
- limit (optional, integer) — количество заказов (по умолчанию 20, максимум 100)
- status (optional, string) — фильтр по статусу (pending, completed, cancelled)

Шаг 3: Посмотреть возвращаемый формат

Ответ (200):
{
  "status": "success",
  "data": [
    {
      "id": "order-123",
      "userId": "user-456",
      "total": 99.99,
      "status": "completed",
      "createdAt": "2023-01-10T10:00:00Z",
      "items": [
        {
          "productId": "prod-789",
          "quantity": 2,
          "price": 49.99
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Шаг 4: Написать код для вызова

// JavaScript
const userId = 'user-456';
const response = await fetch(
  `/api/v1/users/${userId}/orders?page=1&limit=20&status=completed`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer token123',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data.data); // Массив заказов

// TypeScript
interface Order {
  id: string;
  userId: string;
  total: number;
  status: 'pending' | 'completed' | 'cancelled';
  createdAt: string;
}

interface ListOrdersResponse {
  status: 'success' | 'error';
  data: Order[];
  pagination: {
    page: number;
    limit: number;
    total: number;
  };
}

const getOrders = async (userId: string): Promise<Order[]> => {
  const response = await fetch(
    `/api/v1/users/${userId}/orders`
  );
  const data: ListOrdersResponse = await response.json();
  return data.data;
};

Уровни документации API

1. Быстрый старт (Quick Start)

Как начать работать с API за 5 минут:

# 1. Получить API ключ
https://example.com/account/api-keys

# 2. Сделать первый запрос
curl -H "Authorization: Bearer YOUR_API_KEY" \\
  https://api.example.com/v1/hello

# 3. Получить ответ
{ "message": "Hello, World!" }

2. Полная ссылка (API Reference)

Полное описание всех методов, параметров, типов и кодов ошибок.

3. Примеры и сценарии (Examples & Guides)

Практические примеры решения задач:

- Как создать пользователя
- Как обработать платёж
- Как работать с вебхуками
- Как обработать ошибки

4. Best Practices

Рекомендации по использованию:

- Используй pagination для больших списков
- Кэшируй результаты когда возможно
- Обрабатывай rate limiting
- Используй exponential backoff для retry

Части ссылки на API

API Reference
├── Authentication (авторизация)
├── Errors (обработка ошибок)
├── Rate Limiting (ограничения)
├── Resources (ресурсы)
│   ├── Users
│   │   ├── GET /users
│   │   ├── POST /users
│   │   ├── GET /users/{id}
│   │   ├── PUT /users/{id}
│   │   └── DELETE /users/{id}
│   ├── Orders
│   │   ├── GET /orders
│   │   └── ...
│   └── Products
│       └── ...
├── Webhooks (вебхуки)
├── SDKs (библиотеки)
└── FAQ (часто задаваемые вопросы)

Где найти ссылки на API?

1. Официальная документация
   https://docs.example.com/api
   https://api.example.com/docs

2. Swagger / OpenAPI
   https://api.example.com/swagger-ui
   https://api.example.com/api-docs

3. Postman Collection
   import collection из документации

4. GitHub
   README.md в репозитории проекта

Пример полной ссылки на API

# API Reference

## Authentication
Все запросы требуют Authorization заголовок:

Authorization: Bearer YOUR_API_KEY

## Users

### List All Users
`GET /api/v1/users`

**Parameters:**
- page (optional): page number (default: 1)
- limit (optional): items per page (default: 20, max: 100)
- search (optional): search by name or email

**Response:**
```json
{
  "status": "success",
  "data": [

{
  "id": "user-123",
  "name": "John Doe",
  "email": "john@example.com"
}

  ]

}

Status Codes:

• 200: Success
• 401: Unauthorized
• 429: Too Many Requests

### Вывод

Ссылка на API — это **техническая документация**, которая содержит:
- Все доступные endpoints и методы
- Требуемые параметры
- Формат возвращаемых данных
- HTTP коды ответов
- Примеры запросов и ответов
- Ограничения и квоты

Это справочник, который разработчики используют при интеграции API в свои приложения. Хорошая документация API экономит часы на разработку и упрощает жизнь разработчикам.