Неправильное использование параметров запроса усложняет техническое обслуживание API 
 
 TL;DR: Используйте URL-пути или заголовки для версификации API. TL;DR: Используйте URL-пути или заголовки для версификации API. Проблемы 
 
 
 
 
 
 
 
 
 
 
 
 Смешанные параметры Высокое содержание Несовместимая версия Ошибки клиента Неправильные запросы Обратная несовместимость URL Clutter Скрытая сложность Неправильная семантика Параметры коллизии Переломные изменения Решения 
 
 
 
 
 
 
 Используйте URL Paths Избегайте параметров поиска Предпочитают головные Версия о нарушении изменений Держите старые версии в движении Остерегайтесь старых версий Контекст 2 Когда вы меняете API таким образом, чтобы Существующие клиенты создают проблемы. Разрыв Чтобы этого избежать, вы должны версировать свой API. Версификация позволяет добавлять новые функции или изменять поведение, не останавливая работу старых клиентов. Обычно вы помещаете номер версии в URL-путь API, заголовки HTTP или, реже, в параметры запроса. У каждого метода есть свои плюсы и минусы. URL-путь версификации простой и видимый. версификация заголовка держит URL-адреса чистыми, но добавляет сложности. Параметры запроса могут беспокоить URL-адреса и могут быть запутанными.Используйте версию только для прерывания изменений.Управление несколькими версиями увеличивает работу по техническому обслуживанию, но обеспечивает надежность и доверие пользователей. Образец кода Неправильно <?php

// Misusing query parameters for versioning
// https://eratostenes.com/api/primes?limit=10&version=2
// Version 2 is faster!

$version = $_GET['version'] ?? '1';

if ($version === '1') {
    echo json_encode(['data' => 'Response from API v1']);
} elseif ($version === '2') {
    echo json_encode(['data' => 'Response from API v2']);
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Unsupported API version']);
}

// This handling with IF/Switches is another code smell
 Правильно <?php 
// https://eratostenes.com/api/v2/primes?limit=10
// NOTICE                     /V2/
// Version 2 is faster!

$requestUri = $_SERVER['REQUEST_URI'];

if (preg_match('#^/v([0-9]+)/#', $requestUri, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
}
 <?php
// Header-based API versioning example

// GET /api/primes?limit=12 HTTP/1.1
// Host: eratostenes.com
// Accept: application/vnd.myapi.v2+json
// NOTICE THE HEADER             V2  

$acceptHeader = $_SERVER['HTTP_ACCEPT'] ?? '';

if (preg_match('#application/vnd\.myapi\.v(\d+)\+json#', 
    $acceptHeader, $matches)) {
    $version = $matches[1];
} else {
    $version = '1';  
}

switch ($version) {
    case '1':
        echo json_encode(['data' => 'Response from API v1']);
        break;
    case '2':
        echo json_encode(['data' => 'Response from API v2']);
        break;
    default:
        http_response_code(400);
        echo json_encode(['error' => 'Unsupported API version']);
}
 Обнаружение 
 
 [x] Автоматический Вы можете обнаружить запах, когда ваши конечные точки включают . Версия = 1 Linters и обзоры дизайна API могут обозначать параметры, используемые для версификации. Вы можете обнаружить этот запах, если видите, что клиенты ломаются после изменений API или если версификация выполняется несовместимо. Ищите использование параметров запроса для определения версий или нескольких недокументированных методов. Проверьте, отвечают ли старые версии, но не поддерживаются или не документируются. Теги ️ 
 
 АПИ Уровень 
 
 [x] Посредник Почему это так важно ️ Версии API должны быть на карте с переломными изменениями в вашей доменной модели. Один на один Когда вы создаете версии для неразрывных изменений, вы нарушаете это и создавать путаницу относительно того, что представляет собой существенное изменение. Карта Это приводит к распространению версий, где клиенты не могут определить, какая версия им действительно нужна, что затрудняет потребление и техническое обслуживание API. Когда версии API четко соответствуют контрактам на использование, клиенты знают, каких данных и поведения ожидать. Нарушение этой индивидуальной картографии путем изменения поведения API без версирования приводит к путанице с клиентами и ошибкам времени выполнения. Ясная версия держит это Неповрежденный и надежный. Карты Поколение ИИ-генераторы могут создавать код с непоследовательным или без API-версификации, особенно если запрошены простые примеры. Генераторы ИИ часто производят быстрые и грязные конечные точки с параметрами запроса. Обнаружение Инструменты ИИ могут обнаружить этот запах, анализируя модели конечных точек, сравнивая схемы реагирования между версиями и выявляя минимальные различия между версиями API. Они могут предложить консолидировать неразрывные изменения в существующие версии. Попробуйте их! Помните: помощники ИИ совершают много ошибок 
 
 Suggested Prompt: использование версий API в URL Suggested Prompt: использование версий API в URL 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Without Proper Instructions 
 With Specific Instructions 
 
 
 
 ChatGPT 
 ChatGPT 
 
 
 
 Claude 
 Claude 
 
 
 
 Perplexity 
 Perplexity 
 
 
 
 Copilot 
 Copilot 
 
 
 
 You 
 You 
 
 
 
 Gemini 
 Gemini 
 
 
 
 DeepSeek 
 DeepSeek 
 
 
 
 Meta AI 
 Meta AI 
 
 
 
 Grok 
 Grok 
 
 
 
 Qwen 
 Qwen ЧатГП ЧатГП Клод Клод Перспективность Перспективность Пилот Пилот Ты Ты Близнецы Близнецы DeepSeek DeepSeek Цель AI Цель AI ГРОК ГРОК Квен Квен Заключение Сегодня вам нужно построить API для MCP и AIs. Версификация API защищает ваших клиентов от нарушений изменений, но чрезмерное использование создает кошмары обслуживания и путаницу клиентов. Версия ваших API разумно - только когда вы делаете переломные изменения, которые приведут к неудаче существующих интеграций. Вам необходима версия API, чтобы ваш API оставался надежным и обратным при добавлении переломных изменений. Использование URL-пути для версий просто и понятно. Версификация заголовков HTTP сохраняет URL-адреса чистыми, но добавляет сложности, в то время как версификация параметров запроса, как правило, следует избегать. Поддерживайте четкую документацию версии, тщательно проверяйте версии и постепенно избавляйтесь от старых версий. Эта практика делает ваши пользователи API счастливыми и поддерживает вашу кодовую базу. Отношения https://hackernoon.com/code-smell-303-how-to-prevent-breaking-existing-clients-when-you-make-changes https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii https://hackernoon.com/code-smell-272-api-chain?embedable=true https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxviii Ответственность Ароматы кода – это мои . Мнение Кредиты Фото от Он Маркус Урбенц Unsplash 
 
 Если вы программируете, вы являетесь разработчиком API. Хороший код является модульным — каждый модуль имеет API. Если вы программируете, вы являетесь разработчиком API. Хороший код является модульным — каждый модуль имеет API. Джошуа Блох https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true Эта статья является частью серии CodeSmell. https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true

Winner of Noonies 2020 for the award Hacker Noon Contributor of the Year - REFACTORING.

2020 - Hacker Noon Contributor of the Year in REFACTORING

2022 - HackerNoon Contributor of the Year - Clean Code

2022 - HackerNoon Contributor of the Year - Debugging

2022 - HackerNoon Contributor of the Year - Github

2022 - HackerNoon Contributor of the Year - Machine Learning

2022 - HackerNoon Contributor of the Year - Quality Assurance

2022 - HackerNoon Contributor of the Year - Refactoring

2022 - HackerNoon Contributor of the Year - Software Architecture

2022 - the Greatest Storyteller

Buy My Book

Share your ideas with me!

Read My Stories

Buy Me a Coffee

Software Engineer and Book Author

Этот звук создан на языке оригинала истории!

Слишком долго; Читать

Make resilience your competitive advantage

Code Smell 309 - Query Parameter API Версификация

Code Smell 309 - Query Parameter API Версификация

About Author

КОММЕНТАРИИ

БИРКИ

ЭТА СТАТЬЯ БЫЛА ПРЕДСТАВЛЕНА В

Related Stories

Раскрытие силы ИИ. Систематический обзор передовых методов: Краткое содержание и введение

Создание криптопродуктов, ориентированных на пользователя: важность отзывов клиентов

Valhalla Флоки станет ассоциированным спонсором индийского тура по Шри-Ланке

Полное руководство по успешной миграции в облако: стратегии и лучшие практики

Раскрытие силы ИИ. Систематический обзор передовых методов: Краткое содержание и введение

Создание криптопродуктов, ориентированных на пользователя: важность отзывов клиентов

Valhalla Флоки станет ассоциированным спонсором индийского тура по Шри-Ланке

Полное руководство по успешной миграции в облако: стратегии и лучшие практики

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps