編寫一個API，好處包括：自動包含嵌套對象，根本不包含，或者提供一個參數來指定要包含哪些對象？

Question

例如，我們有一個名爲ServiceConfig的實體，其中包含pointer到Service和Professional。如果不包括區域看起來像這樣返回：

{ 
    'type': '__Pointer', 
    'className': 'Service', 
    'objectId': 'q92he840' 
} 

在這一點，他們可以再次查詢檢索服務。但是，他們通常需要Service名稱。在這種情況下，再次查詢以獲得服務是無效的。

選項：

1. 自動返回Service。在這種情況下，我們應該自動返回Industry那Service以及他們需要的情況......同樣適用於所有。好像我們在這裏經常返回數據。

2. 允許他們通過includes參數，該參數指定要包含哪些實體。格式是一個字符串數組，其中使用.可以允許它們包含子類。在這種情況下，['Professional', 'Service.Industry']可以工作。

任何人都可以確定爲什麼任何一種解決方案會比其他解決方案更好？我覺得最後的解決方案是最好的，但是在我看到的API中似乎並不常見。

Answer 1

在發佈初始版本之前，這是一個很好的API設計決策。這兩種方法都是有效的，這一切都取決於您認爲客戶使用您的API的最常見方式。

以下是你可以考慮一些要點：

1. 你可能更喜歡第一種方法，你不給所有的數據前期。有時候是關於效率，有時也與安全有關，並確保只有根據需要和授權才能獲取任何其他重要數據。
2. 實施第二種方法需要您的團隊的更多努力來設計/編碼和測試API。所以你可能想要考慮你想要發佈多少努力1.0
3. 因爲你有嵌套的數據，例如，第二種方法將很好地爲您服務。事實上，有幾個公共API會這樣做。對於例如請查看LinkedIn公共API，尤其是facets部分，您可以在其中指定您希望返回的字段或附加信息。
4. 看看你編寫的一些客戶端應用程序，並且如果你能確定某些數據是否需要預先提供，那麼它可以幫助設計返回數據。
5. 最終監控API使用情況並對調用次數進行一些分析，調用的方法將爲您接下來要做的事提供良好的輸入。

如果我不得不做出選擇並且在努力方面有更多的餘地，那麼即使它是一個簡單的版本，我也會選擇第二種選擇。