クエリパラメータの誤った使用は、APIのメンテナンスを複雑にする 
 
 TL;DR: URL パスまたはヘッダーを使用して API バージョニングを行う。 TL;DR: URL パスまたはヘッダーを使用して API バージョニングを行う。 トラブル 
 
 
 
 
 
 
 
 
 
 
 
 混乱したパラメータ 高保守 不一致のバージョン クライアントエラー 誤った要望 Backward incompatibility(バックバックバック) URLクラッター 隠れた複雑さ 間違ったセマンティクス パラメーターコリクション ブレイク変更 ソリューション↓ 
 
 
 
 
 
 
 URL パス クエリパラメータを避ける 優先頭部 バージョン: Breaking Changes 古いバージョンを動かす 古いバージョンを慎重に コンテキスト API を変更する場合 既存の顧客が問題を生み出す ブレーキ これを避けるには、APIをバージョン化する必要があります。 バージョニングは、古いクライアントを停止することなく、新しい機能を追加したり、行動を変更したりすることができます。 通常、バージョン番号をAPI URL パス、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の変更後にクライアントが破損するか、バージョニングが不一致な場合に検出できます。 クエリパラメータを使用して、バージョンを定義するか、複数の非文書化された方法を検索します。 古いバージョンがまだ応答しているが、明示的に維持されていないか、文書化されていないかを確認してください。 タグ ️ 
 
 APIs レベル 
 
 (x) 中間 なんでバッテリーが大事なの️ API バージョン should map あなたのドメインモデルに変化をもたらします。 ひとつひとつ 非破壊的な変更のためのバージョンを作成すると、これを破ります。 重要な変化を意味するものについての混乱を生み出す。 マップ これは、クライアントが実際にどのバージョンが必要かを決定できないバージョンの拡張につながり、APIを消費し、維持するのが難しくなります。 API バージョンが使用契約に明確に一致する場合、顧客はどのようなデータや行動を期待できるかを知っています。 バージョニングなしでAPIの動作を変更することによってこの一対一マッピングを破ることは、クライアントの混乱とランタイムエラーを引き起こします。 明確なバージョンはこれを保持する 完璧で信頼できる マップ 世代 AI ジェネレーターは、非一貫性あるいは API バージョニングなしのコードを作成する場合があります、特に単純な例を要求する場合です。 AI ジェネレーターは、しばしばクエリパラメータを用いた速く汚れたエンドポイントを作成します. They optimize for speed, not semantics. 検出 ↓↓ AI ツールは、エンドポイントパターンを分析し、バージョン間の対応スケジュールを比較し、API バージョン間の最小の違いを特定することで、この臭いを検出することができます。 彼らは、既存のバージョンに非破壊的な変更を統合することを提案することができます。 ぜひお試しください!↓↓ 注意:AIアシスタントは多くの間違いを犯す 
 
 Suggested Prompt: use API versions in the url. URL で API バージョンを使用する Suggested Prompt: use API versions in the url. URL で API バージョンを使用する 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 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 チャット チャット クラウド クラウド 戸惑い 戸惑い パイロット パイロット あなた あなた 双子 双子 ディープ検索 ディープ検索 ターゲット AI ターゲット AI グロック グロック QWEN QWEN 結論 ↓ 今日、MCPとAIのためのAPIを構築する必要があります。 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 ディスカレーター Code Smells Are Mine(コードの匂いは私のもの) . 意見 クレジット↓ 写真 by は マルクス・ウルベンツ 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

海を航海する: データレイクを使用した本番環境レベルの RAG アプリケーションの開発

フォーラムからフィードへ: ソーシャルメディアアルゴリズムがデジタルインタラクションを形作る仕組み

AI/ML データレイクのリファレンスアーキテクチャを構築するためのアーキテクトガイド

ユニークなエコシステムを支えるビットコインUTXOのモデル

海を航海する: データレイクを使用した本番環境レベルの RAG アプリケーションの開発

フォーラムからフィードへ: ソーシャルメディアアルゴリズムがデジタルインタラクションを形作る仕組み

AI/ML データレイクのリファレンスアーキテクチャを構築するためのアーキテクトガイド

ユニークなエコシステムを支えるビットコインUTXOのモデル

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps