api-tutorial-writer

Подход прогрессивной сложности

• Начинайте с аутентификации и базовых запросов
• Постепенно усложняйте через реалистичные случаи использования
• Заканчивайте продвинутыми возможностями и обработкой ошибок
• Включайте раздел "Быстрый старт" для опытных разработчиков
• Предоставляйте как curl примеры, так и код SDK

Основные разделы туториала

1. Предварительные требования - Необходимые знания, инструменты и аккаунты
2. Настройка аутентификации - Пошаговая реализация авторизации
3. Базовые операции - CRUD операции с полными примерами
4. Реальные сценарии - Практические случаи использования
5. Обработка ошибок - Частые ошибки и решения
6. Лучшие практики - Производительность, безопасность и оптимизация
7. Устранение неполадок - FAQ и руководство по отладке

Аутентификация с API ключом

```bash

# curl пример

curl -X GET "https://api.example.com/v1/users" \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json"

```

```javascript

// JavaScript пример

const apiKey = 'your-api-key';

const response = await fetch('https://api.example.com/v1/users', {

method: 'GET',

headers: {

'Authorization': Bearer ${apiKey},

'Content-Type': 'application/json'

}

});

const data = await response.json();

```

OAuth 2.0 Flow

```python

# Python OAuth пример

import requests

from requests_oauthlib import OAuth2Session

# Шаг 1: Получаем URL авторизации

client_id = 'your-client-id'

redirect_uri = 'https://your-app.com/callback'

authorization_base_url = 'https://api.example.com/oauth/authorize'

oauth = OAuth2Session(client_id, redirect_uri=redirect_uri)

authorization_url, state = oauth.authorization_url(authorization_base_url)

print(f'Please go to {authorization_url} and authorize access.')

# Шаг 2: Обмениваем код на токен

token_url = 'https://api.example.com/oauth/token'

token = oauth.fetch_token(token_url, authorization_response=callback_url,

client_secret='your-client-secret')

# Шаг 3: Делаем аутентифицированные запросы

response = oauth.get('https://api.example.com/v1/profile')

profile_data = response.json()

```

Полные CRUD операции

```bash

# CREATE - Добавляем новый ресурс

curl -X POST "https://api.example.com/v1/tasks" \

-H "Authorization: Bearer YOUR_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"title": "Complete API tutorial",

"description": "Write comprehensive API documentation",

"due_date": "2024-02-15",

"priority": "high"

}'

# Ответ:

# {

# "id": "task_123",

# "title": "Complete API tutorial",

# "status": "pending",

# "created_at": "2024-01-15T10:30:00Z"

# }

```

```python

# READ - Получаем ресурсы с фильтрацией

import requests

url = "https://api.example.com/v1/tasks"

headers = {

"Authorization": "Bearer YOUR_API_KEY",

"Content-Type": "application/json"

}

# Получаем задачи с фильтрами

params = {

"status": "pending",

"priority": "high",

"limit": 10,

"offset": 0

}

response = requests.get(url, headers=headers, params=params)

tasks = response.json()

for task in tasks['data']:

print(f"Task: {task['title']} - Status: {task['status']}")

```

Исчерпывающая структура ответа об ошибке

```json

{

"error": {

"code": "VALIDATION_ERROR",

"message": "The request contains invalid parameters",

"details": [

{

"field": "due_date",

"issue": "Date must be in ISO 8601 format"

}

],

"request_id": "req_abc123",

"documentation_url": "https://docs.api.example.com/errors#validation"

}

}

```

Реализация обработки ошибок

```javascript

async function makeAPIRequest(endpoint, options = {}) {

try {

const response = await fetch(https://api.example.com/v1${endpoint}, {

...options,

headers: {

'Authorization': Bearer ${API_KEY},

'Content-Type': 'application/json',

...options.headers

}

});

if (!response.ok) {

const errorData = await response.json();

switch (response.status) {

case 400:

throw new Error(Validation Error: ${errorData.error.message});

case 401:

throw new Error('Authentication failed. Check your API key.');

case 429:

throw new Error('Rate limit exceeded. Please wait before retrying.');

case 500:

throw new Error('Server error. Please try again later.');

default:

throw new Error(API Error: ${errorData.error.message});

}

}

return await response.json();

} catch (error) {

console.error('API Request failed:', error.message);

throw error;

}

}

```

Реализация ограничения скорости

```python

import time

import requests

from functools import wraps

def rate_limited(max_calls_per_second=10):

def decorator(func):

last_called = [0.0]

@wraps(func)

def wrapper(args, *kwargs):

elapsed = time.time() - last_called[0]

left_to_wait = 1.0 / max_calls_per_second - elapsed

if left_to_wait > 0:

time.sleep(left_to_wait)

ret = func(args, *kwargs)

last_called[0] = time.time()

return ret

return wrapper

return decorator

@rate_limited(max_calls_per_second=5)

def api_call(url, headers):

return requests.get(url, headers=headers)

```

Обработка пагинации

```python

def get_all_resources(base_url, headers):

all_resources = []

next_url = f"{base_url}?limit=100"

while next_url:

response = requests.get(next_url, headers=headers)

data = response.json()

all_resources.extend(data['data'])

# Обрабатываем разные стили пагинации

if 'pagination' in data:

next_url = data['pagination'].get('next_url')

elif 'meta' in data and data['meta'].get('has_more'):

offset = len(all_resources)

next_url = f"{base_url}?limit=100&offset={offset}"

else:

next_url = None

return all_resources

```

Поддержка нескольких языков

```go

// Go пример

package main

import (

"bytes"

"encoding/json"

"fmt"

"net/http"

)

type Task struct {

ID string json:"id,omitempty"

Title string json:"title"

Description string json:"description"

Status string json:"status,omitempty"

}

func createTask(apiKey string, task Task) (*Task, error) {

jsonData, err := json.Marshal(task)

if err != nil {

return nil, err

}

req, err := http.NewRequest("POST", "https://api.example.com/v1/tasks", bytes.NewBuffer(jsonData))

if err != nil {

return nil, err

}

req.Header.Set("Authorization", "Bearer "+apiKey)

req.Header.Set("Content-Type", "application/json")

client := &http.Client{}

resp, err := client.Do(req)

if err != nil {

return nil, err

}

defer resp.Body.Close()

var createdTask Task

if err := json.NewDecoder(resp.Body).Decode(&createdTask); err != nil {

return nil, err

}

return &createdTask, nil

}

```

Рекомендации по качеству туториала

• Тестируйте каждый пример: Убедитесь, что все примеры кода функциональны и проверены
• Включайте ожидаемые результаты: Показывайте точно, как выглядят ответы
• Предоставляйте контекст: Объясняйте, почему рекомендуются определенные подходы
• Рассматривайте крайние случаи: Покрывайте частые ошибки и способы их избежания
• Сохраняйте реалистичность примеров: Используйте реальные сценарии, а не надуманные примеры
• Регулярно обновляйте: Поддерживайте актуальность при изменениях API
• Разные стили обучения: Включайте визуальные материалы, пошаговые руководства и справочные материалы
• Обратная связь от сообщества: Включайте вопросы и предложения разработчиков

Советы по структуре документации

• Используйте последовательное форматирование для всех блоков кода
• Включайте готовые к копированию примеры
• Предоставляйте как минимальные, так и исчерпывающие примеры
• Добавляйте примерное время выполнения для каждого раздела
• Включайте ссылки на связанные концепции и продвинутые темы
• Предлагайте несколько подходов к реализации, когда это уместно