👱 🌡️ 👨🏼‍🍳 後方互換性の維持：Icebergの喫水線について 🤲🏽 ♾ ☹️

拡張可能なAPIの設計原則について説明する前に、考慮すべき衛生上の最小値があります。API開発者が自分の責任範囲を特定する責任がもう少しあれば、膨大な数の問題は発生しなかったでしょう。

1.最小限の機能を提供する

いつでも、APIは氷山のようなものです。つまり、目に見える（文書化された）部分と目に見えない文書化されていない部分があります。優れたAPIでは、これら2つの部分は、実際の氷山の表面部分と水中部分の1から10のように、互いに大まかに関連しています。2つの明らかな理由があります。

コンピューターは複雑なことを簡単にするために存在し、その逆ではありません。開発者がAPIの上に作成するコードは、複雑な問題の解決策を簡単かつ簡潔に説明する必要があります。開発者が自分で作成したよりも多くのコードをAPIに作成することを余儀なくされた場合、ここで問題が発生しました。おそらく、そのようなAPIは単に必要ありません。
APIから機能を削除することは、重大な損失なしには不可能です。一部の機能を提供することを約束した場合は、「永久に」提供する必要があります（このメジャーバージョンのAPIのサポートが終了するまで）。機能がサポートされていないことを宣言することは複雑なプロセスであり、消費者との潜在的な競合を伴います。

ルール1は最も単純です。一部の機能を公開する必要がない場合は、公開する必要はありません。これは次のように定式化できます。パブリックAPIのすべてのエンティティ、すべてのフィールド、すべてのメソッドは製品ソリューションです。エンティティが文書化されるのには十分な理由があるはずです。

2.灰色の領域と控えめな表現を避けます

機能を維持するためのあなたのコミットメントは、可能な限り明確でなければなりません。これは、文書化されていない機能へのアクセスをネイティブに制限する方法がない環境やプラットフォームに特に当てはまります。残念ながら、開発者は、非公開の機能を「見つけた」場合、それを使用できると信じていることがよくあります。したがって、APIメーカーはそれをサポートする義務があります。したがって、そのような「発見」に関する会社の方針を明確に策定する必要があります。そうすれば、隠された機能が不正に使用された場合でも、少なくともドキュメントを参照して、コミュニティの目から見て正式に正しいものにすることができます。

ただし、API開発者自身がそのような灰色の領域を正当化することがよくあります。たとえば、次のようになります。

エンドポイント応答に文書化されていないフィールドを与える。
— , , ..;

. , , .

. , : - , , ?

1. SDK .

//  
let order = api.createOrder();
//   
let status = api.getStatus(order.id);

, - . , id 404

, , . , strong eventual.

? , . , — . , — .

: «, !» — , , . , , createOrder

, SDK - :

let order = api.createOrder();
let status;
while (true) {
    try {
        status = api.getStatus(order.id);
    } catch (e) {
        if (e.httpStatusCode != 404 || timeoutExceeded()) {
            break;
        }
    }
}
if (status) {
    …
}

, , , . API, createOrder

SDK , getStatus

.

— API. , , .

2. :

let resolve;
let promise = new Promise(
    function (innerResolve) {
        resolve = innerResolve;
    }
);
resolve();

, callback-, new Promise

, resolve

resolve()

. : new Promise

callback-.

, , . API — . , ; , , API. .

3. , API , :

//    
//     
//   
object.animateWidth('100px', '500px', '1s');
//     
object.observe('widthchange', observerFunction);

: observerFunction

? , SDK 10 — observerFunction 10 '140px', '180px' .. '500px'. API — , observerFunction

.

- — , , , , SDK 10 . , , observerFunction

'500px' - — - .

— callback — .

4. , , :

GET /v1/orders/{id}/events/history
→
{
    "event_history": [
        {
            "iso_datetime": "2020-12-29T00:35:00+03:00",
            "new_status": "created"
        },
        {
            "iso_datetime": "2020-12-29T00:35:10+03:00",
            "new_status": "payment_approved"
        },
        {
            "iso_datetime": "2020-12-29T00:35:20+03:00",
            "new_status": "preparing_started"
        },
        {
            "iso_datetime": "2020-12-29T00:35:30+03:00",
            "new_status": "ready"
        }
    ]
}

, - « », . .. "preparing_started", "ready", "payment_approved". , - — , . , , .

, (, - ) - , - — , . , - , . . - ; , .

-, ; -, "payment_approved" "preparing_started" ( — , , ) .

, , — . - , .

, , - . - , «». , , . - , .. -, , , - , .

« -» — , , - , . . «» — API; — « », III.

これは、API開発に関する本の将来の章のドラフトです。作業はGithubで行われます。同じ章の英語版がメディアで公開されています。redditで共有していただければ幸いです。プラットフォームのポリシーに従って私自身はできません。

後方互換性の維持：Icebergの喫水線について

More articles: