بقية API الإصدار (الإصدار فقط التمثيل، وليس المورد نفسه)

Question

ألقيت نظرة على أفضل الممارسات للحصول على إصدار API؟, لكنني لست مقتنعا تماما بالإجابة، لذلك أنا أسأل عن جزء الإصدار مرة أخرى بمثال أكثر تحديدا. أواجه اثنين من URIS (واحد مع إصدار كجزء من URI و ONE بدون):

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123             

أواجه شكوكي سواء كان الرابط الأول يعبر عن فكرة الراحة. وجدت http://xxxx/v1/user/123 مربكة لأنها تشير إلى أنه سيكون هناك نسخة API أعلى يوما ما http://xxxx/v2/user/123. وبعد ولكن هذا لا معنى له في شروط الراحة، وإصدار API نفسه هو HTTP 1.0 أو 1.1، والذي يتم إرساله بالفعل داخل طلب HTTP. يختلف عرض مراكز Resource Resource هذا من واجهات API الأخرى مثل الصابون أو واجهات Java-واجهات (حيث من الشائع أن يكون لديك إصدارات API بالأسماء المؤهلة).

في راحة الشيء الوحيد الذي يجعل النسخة منطقية هو تمثيل هذا المورد (مثل الحقول الجديدة تضاف أو إزالتها). تنتمي هذه النسخة إلى جزء من مفاوضات المحتوى مثل:

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

يمكن للمرء أيضا أن يجادل أيضا بأن هذا الإصدار قد يكون مفاوضات المحتوى جزءا من URI داخل المسار، لكنني أجد أنها مضادة بديهية، لأنك يمكن أن ينفدو مع مختلف URIs لنفس المورد وأن تضطر إلى الحفاظ على إعادة توجيهات في مرحلة ما.

لتلخيص: في الباقي Uris، لا يوجد إصدار API، الإصدار فقط من تمثيل المورد. إصدار إصدار التمثيل ينتمي إلى مفاوضات المحتوى (مثل QueryParam أو HTTP "قبول").

ما رأيك؟ في أي الأشياء التي لا توافق / توافق؟

Answer 1

أنا أتفق تماما؛ يعرب URI عن هويته، ولا تتغير الهوية عند تقديم إصدار جديد. قد يكون هناك أوريس جديد لمفاهيم إضافية، بطبيعة الحال، وقد إعادة توجيه URIS الموجود ... ولكن بما في ذلك "V2" في رائحة URI Subcish بالنسبة لي.

لاحظ أن هذا لا علاقة له بالراحة، حقا، كما هو الحال من منظور الراحة، كل شيء فقط الشخصيات.

Answer 2

أنت استطاع الاستماع إلى X-API-Version رئيس طلب HTTP. إذا كان الرأس موجودا، فيجب أن يستخدم الخادم الإصدار من API. إذا كان الرأس غير موجود، فقد يستخدم الخادم أحدث إصدار من API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Answer 3

ما يستحق، وأنا أتفق معك مانويل. يمكنك أن ترى التفكير في هذا السؤال كيفية استراحة الإصدار URIS

هناك الكثير من الأشخاص الذين يبدو أنهم لا يتفقون لكنني لا أعرف. ما يبدو عنوان URL الخاص بك حقا ليس له تأثير كبير على عميلك طالما احترم قيود النص التشعبي.

Answer 4

أوافق على أنك لا ترغب في معرفة إصدارات في URIS من الموارد المقدمة في API الخاص بك. هذا يجعلهم ليسوا "رائعون". توافق أيضا على أن ذلك هو تمثيلات غير المرجح أن تتغير.

ومع ذلك، فإنها تقوم برفع مسألة ما يحدث عند تغيير محتويات تمثيل معين. على سبيل المثال، إذا كان تمثيل JSON الأصلي ل Frobnitz هو

{"x": "bam", "y": "hello"}

وتريد إضافة حقل "z" قد تشعر أنه يجب أن يكون لدى العميل بعض الوعي بأننا الآن على الإصدار 2 من نظام البيانات.

أنا لست متأكدا من هذا. أعتقد أنك حصلت على بعض الخيارات:

• اجعل عملائك مرنا في مواجهة تمثيلات متغيرة بلطف. في المثال أعلاه، ما زلنا نولد قاموس JSON.
• إذا كان يجب عليك، ضع إصدارا في التمثيل نفسه (حقل إصدار في هذا المثال). من خلال القيام بذلك، تعلن بفعالية تمثيل فرعي ضمن نوع محتوى JSON. أعتقد أن هذا هو الحد جدا على الرغم من.
• استخدم أنواع MIME الخاصة بك وإصدارها: تطبيق / X-My-My-Spon-JSON1.0، تطبيق / X-My-Special-JSON1.1. هذا يسمح لك بإصدار تمثيلاتك بشكل مستقل عن بعضها البعض. مرة أخرى، مع هذا الشخص الذي تقوم به طلبا كبيرا على عملائك لمعرفة ما يجري.

بشكل عام، أعتقد أنك تريد تحسين واجهة برمجة التطبيقات الخاصة بك وتمثيلاتك للعملاء الذين لم تحترموا بنفسك؛ تلك التي سيخلقها الأشخاص الآخرون عند اكتشاف مواردك. أعتقد أن هذا مفيد حتى في الحالة عندما تقوم بعمل شيء خاص لأنه يبني في قيد تصميم مفيد سيساعد على جعل نظامك أكثر قوة.

Answer 5

وجدت http: // xxxx / v1 / المستخدم / 123مربكة لأنها تشير إلى أنه سيكون هناك نسخة API أعلى يوما ما http: // xxxx / v2 / user / 123

لا يقترح ذلك - ومع ذلك لديك هذه القدرة في المستقبل.

ولكن هذا لا معنى له في شروط الراحة، وإصدار API نفسه هو HTTP 1.0 أو 1.1، والذي يتم إرساله بالفعل داخل طلب HTTP.

لا يجب أن يكون إصدار Api الخاص بك وإصدار HTTP الذي تستخدمه لتقديم الطلبات متساويا.

يمكن للمرء أيضا أن يجادل أيضا بأن هذا الإصدار قد يكون مفاوضات المحتوى جزءا من URI داخل المسار، لكنني أجد أنها مضادة بديهية، لأنك يمكن أن ينفدو مع مختلف URIs لنفس المورد وأن تضطر إلى الحفاظ على إعادة توجيهات في مرحلة ما.

ما يرام للحصول على الإصدار كمعلمة URI كما أظهرت.

http: // xxx / user / 123؟ v = 1 -> للحصول على روابط بيرما / الارتباطات التشعبية

Answer 6

يمكن أن يكون نهج آخر هو القول أن "تمثيل واحد لديه واجهات برمجة التالية متعددة":

http://xxx/user/123/api/1.json

وإذا كنت ترغب في ذلك، يمكنك إرجاع التمثيل باستخدام أحدث برامج API عند طلب هذا الأمر:

http://xxx/user/123.json

أنا شخصيا أحب الحلول الأخرى بشكل أفضل ولكن هذا نهج آخر لم أر اقترح هنا بعد.

Answer 7

للراحة، ما ينسون معظم الإجابات هو عنصر البيانات. أفترض أن إصدار API متعدد الإصدار لا يزال يشارك في نفس طبقة البيانات. هذا يعني أن طبقة البيانات يجبرك على التفكير بطريقة متوافقة مع الوراء. التغييرات الكبيرة التي يجب القيام بها لا يمكن القيام بها فقط إذا تغير API الخاص بك بطريقة متوافقة مع الوراء. في الممارسة العملية، هذا يعني أنه تتم إضافة خصائص إضافية بصمت إلى كياناتك أثناء استخدام الاستهلاك حسب التاريخ في وثيقة API الخاصة بك للإشارة إلى متى سيتم إزالة شيء ما. من الناحية المثالية، يمكنك استخدام نظام تسجيل مع عنوان البريد الإلكتروني للمستخدمين الرئيسيين ل API الخاص بك، حتى تتمكن من إطلاعهم على الاستهلاك داخل نطاق معين (A La Facebook). لذلك، لا أعتقد أنك بحاجة إلى تحديد إصدار في أي مكان.