API versiya qaydaları?

Web xidmətinin REST API versiyasını idarə etmək üçün hər hansı bir təlimat və ya təlimat varmı?

AWS'nin son nöqtə URL'sində versiya nəzarətini həyata keçirdiyini fərq etdim. Bu, tək yoldurmu və ya eyni məqsədə nail olmaq üçün başqa yollar var? Bir neçə yol varsa, hər birinin üstünlüyü nədir?

878
23 дек. Swaroop CH 23 dek ilə təyin. 2008-12-23 18:32 '08 saat 18:32 'da 2008-12-23 18:32
@ 7 cavab

Bu yaxşı və çətin bir sual. URI dizayn teması eyni zamanda REST API-nın ən mühüm hissəsidir və bu səbəbdən potensial olaraq bu API istifadəçilərinə uzunmüddətli öhdəlik götürür .

Tətbiqin təkamülündən və daha az dərəcədə onun API bir həyat faktı olduğundan və hətta bir proqramlaşdırma dili kimi görünür bir kompleks məhsulun təkamülünə bənzəyirsə, URI'nin dizaynı daha az təbii məhdudiyyətlərə malik olmalıdırzaman keçməməlidir . Ərizə və API-lərin müddəti uzadıldığı təqdirdə, ərizə və API istifadəçiləri üçün çox böyük öhdəlikdir.

Digər tərəfdən, həyatın başqa bir gerçəyi, API vasitəsilə istehlak ediləcək bütün qaynaqları və onların aspektlərini öngörmek çətindir. Xoşbəxtlikdən, Apocalypse əvvəli istifadə olunacaq bütün API inkişaf etdirməyə ehtiyac yoxdur. Bütün resurs endpointslarını və hər bir resurs nümunəsinin və resursın ünvanlama sxemini düzgün şəkildə müəyyən etmək kifayətdir.

Zamanla, hər bir xüsusi qaynaq üçün yeni resurslar və yeni xüsusiyyətlər əlavə etməli ola bilərsiniz, lakin API istifadəçilərinin müəyyən resurslara çıxış üçün istifadə etdiyi üsul resurs ünvanlama sxemi ictimaiyyətə çatdırıldıqdan və nəticədə yekunlaşdıqdan sonra dəyişməyəcəkdir.

Bu üsul HTTP verb semantikasına (məsələn, PUT həmişə yeniləməlidir / dəyişdirilməlidir) və API-nın əvvəlki versiyalarında dəstəklənən HTTP status kodlarına aiddir (insan müdaxiləsi olmadan işləyən API müştəriləri bu kimi işləməyə davam edə biləcək şəkildə işə davam etməlidirlər) ).

Bundan əlavə, URI-də API versiyasının yerləşdirilməsindən sonra, hipermedia konsepsiyasını tətbiqi dövlət mühərriki (Roy T. Fielding PhD-də göstərilən) pozur, zamanla dəyişən resurs / URI ünvanına malikdirsə, API versiyalarının saxlanılmadığını resurs URI'ları uzun müddətdir , yəni API istifadəçiləri asılı ola biləcək resurs URI'ları, permalinks olması lazımdır .

Əlbəttə , API versiyasını əsas URI-yə yerləşdirə bilərsiniz , lakin yalnız ağıllı və məhdud istifadə üçün, məsələn, API- nin yeni versiyası ilə işləyən bir API müştərisinin disk rastlanması üçün . Versiya ilə bu cür API məhdudlaşdırıla bilər və yalnız API istifadəçilərinin məhdud qruplarına (məsələn, qapalı beta versiyaları ilə) aid edilə bilər. Əks halda siz lazım olmadığı yerə girov verirsiniz.

API versiyalarının saxlanılmasına dair bir neçə fikir, onların etibarlılığı. Web xidmətlərini (Java, .NET, PHP, Perl, Rails və s.) Tətbiq etmək üçün istifadə olunan bütün proqramlaşdırma platformaları / dilləri veb xidmət endpointslarını əsas URI-yə bağlamağa kömək edir. Beləliklə, API-nin müxtəlif versiyalarında faylların / dərslərin / metodların toplusunu toplamaq və saxlamaq asandır.

POV API istifadəçilərinin API-nın xüsusi bir versiyası ilə işləməsi və API-nın müəyyən bir versiyasına bu olduqca aydındır, lakin yalnız məhdud müddət üçün, yəni inkişaf zamanı.

API-də, POV API API-lərin müxtəlif versiyalarını sürət versiyası idarəetmə sistemlərindən istifadə edərək paralel olaraq saxlamağı daha asandır, bu da faylları ən kiçik vahid (mənbə kodu versiyası) kimi işləyir.

Bununla birlikdə, URI-də yaxşı görünən API versiyaları ilə əlaqədar bir xəbərdarlıq var: API tarixinin URI dizaynında görünən və aparılacağı üçün bu yanaşmaya etiraz edə bilərsiniz və buna görə də REST tövsiyələrinə zidd olan vaxt dəyişir . Razıyam!

Bu ağlabatan etirazın ətrafında qalmaq üçün API-nın ən son versiyasını effektiv olmayan API-nin URI bazasında tətbiq etməkdir. Bu halda, API müştəri developers seçə bilər:

  • sonuncuna qarşı inkişaf etsin (zəif müştəri dizaynını poza biləcək API-lərin mümkün dəyişikliklərindən qoruyan bir tətbiqə dəstək vermək üçün vəd ver ).

  • API-nin müəyyən bir versiyasına (aydın olur) bağlıdır, lakin yalnız məhdud bir müddətdir

Məsələn, əgər v3.0 API API-nın ən son versiyasıdırsa, aşağıdakı ikisi alias olmalıdır (məsələn, bütün API istəkləri ilə eyni şəkildə davranmalıdır):

  http: // shonzilla / api / customers / 1234 http: // shonzilla / api /v3.0 / customers / 1234 http: // shonzilla / api / v3 / customers / 1234

Bununla yanaşı, köhnə API-yə işarə etməyə çalışan API müştəriləri API-nın ən son versiyasını istifadə etmələri barədə məlumatlandırılmalıdır , əgər istifadə etdiyin API-nın versiyası köhnəlmişsə və ya artıq dəstəklənməsə . Beləliklə, köhnəlmiş URI-lərdən hər hansı birinə giriş:

 http: // shonzilla / api /v2.2 / customers / 1234 http: // shonzilla / api /v2.0 / customers / 1234 http: // shonzilla / api / v2 / customers / 1234 http: // shonzilla / api / v1.1 / customers / 1234 http: // shonzilla / api / v1 / customers / 1234

HTTP Konumun başlığı ilə birlikdə istifadə edilən redirection-i göstərən HTTP 30x statusu kodlarından birini geri qaytarmalı və resursun URI-in müvafiq versiyasına yönəldir ki, bu da eynidır:

  http: // shonzilla / api / customers / 1234

API versiyası nəzarət skriptlərinə uyğun olan ən azı iki HTTP redirect status kodları var:

  • 301 İstənilən URI ilə bir resursın davamlı olaraq fərqli URI-ə (API versiyası məlumatı olmayan bir qayda nümunəsinin daimi dəyəri olmalıdır) hərəkət etdiyini bildirən daimi olaraq hərəkət edir. Bu statusu kodu API-nin müvəqqəti qaynağının qaynaqlı qaynağını permalink qaynaq istinadı ilə əvəz etməsi barədə məlumatlı olan API-nın köhnəlmiş / dəstəklənməmiş bir versiyasını təyin etmək üçün istifadə edilə bilər.

  • İstənilən resurs müvəqqəti olaraq başqa yerdə yerləşdirildiyini ifadə edərək, istənilən URI hələ də dəstəklənə bilər. Bu status kodu qeyri-versiyalı URI-nin müvəqqəti olaraq istifadə edilmədiyi və müraciətin bir yönlendirme ünvanı ilə təkrarlanmalı olduqda faydalı ola bilər (məsələn, APİ'nin əlaqədar versiyası ilə bir URI-yə işarə edir) və müştərilərin onu istifadə etməyə davam etməsini (məsələn, Permalinks) .

  • digər ssenarilər HTTP 1.1 spesifikasiyasında 3 - cü fəsildə yönləndirilir

685
29 дек. Cavab Shonzilla 29 dekabrda verilir. 2008-12-29 23:24 '09 at 23:24 2008-12-29 23:24

URLdə versiyalar olmalı. Bu versiyada sizdən soruşduğunuz resursun "fikri" ilə heç bir əlaqəsi yoxdur. URL'yi istədiyi konsepsiyanın yolu kimi təqdim etməlisiniz, maddənin necə qaytarılacağına baxmayaraq. Versiyası bir obyektin anlayışını deyil, bir obyektin təmsil olunmasını tələb edir. Digər plakatlar dedikləri kimi, tələb formasındakı formatı (versiyası daxil olmaqla) göstərməlisiniz.

Sürümleri olan URL'ler üçün tam HTTP sorğusuna baxırsınızsa, belə görünür:

 (BAD WAY TO DO IT): http://company.com/api/v3.0/customer/123 ====> GET v3.0/customer/123 HTTP/1.1 Accept: application/xml <==== HTTP/1.1 200 OK Content-Type: application/xml <customer version="3.0"> <name>Neil Armstrong</name> </customer> 

Başlıq istənilən görünüşü olan bir simli ("Qəbul: ərizə / xml") ehtiva edir. Bu versiya getməlidir. Göründüyü kimi, hər kəs eyni şəkildə fərqli formatlarda istəyə bilər və müştərinin nə istədiyini soruşa bilməsi üçün səssizdir. Yuxarıdakı misalda, müştəri istədiyi şeyin əsl təmsilçisindən deyil, XML-nin XML təqdimatını tələb edir. Server, nəzəri cəhətdən, istəklə tamamilə əlaqəsi olmayan bir şeyə qayıda bilərdi, əgər XML idi və bunun səhv olduğunu başa düşmək üçün təhlil etmək lazımdır.

Ən yaxşı şəkildə:

 (GOOD WAY TO DO IT) http://company.com/api/customer/123 ===> GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+xml <=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+xml <customer> <name>Neil Armstrong</name> </customer> 

Daha sonra deyək ki, müştərilər XML-nin çox vacib olduğunu düşünürlər və indi onlar JSON-a lazımdır. Digər nümunələrdə eyni müştəri üçün yeni bir URL olmalıdır, beləliklə:

border=0
 (BAD) http://company.com/api/JSONv3.0/customers/123 or http://company.com/api/v3.0/customers/123?format="JSON" 

(və ya belə bir şey). Əslində, hər bir HTTP sorğusu aradığınız formatı ehtiva edir:

 (GOOD WAY TO DO IT) ===> GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+json <=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+json {"customer": {"name":"Neil Armstrong"} } 

Bu metodu istifadə edərək, dizaynda daha çox azadlıq var və həqiqətən REST-in orijinal fikirlərinə riayət edirsiniz. Müştərilərə narahat olmayan versiyaları dəyişdirə və ya API dəyişiklikləri kimi müştəriləri tədricən dəyişə bilərsiniz. Görünüşü dəstəkləməyə qərar verməsəniz, HTTP statusu kodu və ya xüsusi kodları olan istəklərə cavab verə bilərsiniz. Müştəri həmçinin cavabın düzgün formatda olduğunu təsdiq edə və XML-ni yoxlaya bilər.

Bir çox digər faydalar var və bunlardan bəzisini blogumda müzakirə edirəm: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html

Son nümunə, versiyanın URL-ə köçürüldüyünü göstərir. Nesnenin içindəki bəzi məlumatlara ehtiyac duyduğunuzu düşünün və müxtəlif obyektlərinizi (müştərilər v3.0, sifarişlər v2.0 və obyektə v4.2) yoxlayın. Müştəriyə göstərmək üçün lazım olan pis URL burada:

 (Another reason why version in the URL sucks) http://company.com/api/v3.0/customer/123/v2.0/orders/4321/ 
273
19 июля '11 в 19:08 2011-07-19 19:08 cavab 19 iyul 19: 00 -da saat 19: 00 -da verilir. 2011-07-19 19:08

Biz versiyanı URL-də yerləşdirmək üçün praktik və faydalı tapdım. Bu bir baxışda istifadə etdiyiniz şeyi anlamaq asanlaşdırır. Qəbul edilmiş cavabı göstərir ki, biz fayldan / foo / foo / (son versiyaların) mövcudluğu, daha qısa / təmiz URL və s. Üçün istifadə edirik.

Qarşılıqlı uyğunluğun əvvəldən saxlanılması tez-tez bahalı və / və ya çox mürəkkəbdir. Burada təklif olunan köhnəlmələr, istiqamətləndirmələr, sənədlər və digər mexanizmlər barədə əvvəlcədən xəbərdarlıq etmək istəmirik.

99
04 янв. Cavab Yoav Şapirə tərəfindən verilir 04 Yanvar 2011-01-04 23:57 '11 da 23:57 2011-01-04 23:57

Mən resursların doğru təqdimatının REST metoduna daha uyğun olduğunu qəbul edirəm ... lakin xüsusi MIME növləri ilə (və ya bir versiya parametrini əlavə edən MIME növləri) bir böyük problem HTML və JavaScript-də Qəbul və Content-Tür başlıqlarını yazmaq üçün zəif dəstəkdir .

Məsələn, HTML yaratmaq üçün aşağıdakı HTML5 başlıqları ilə POST üçün IMO yarada bilməzsiniz:

 Accept: application/vnd.company.myapp-v3+json Content-Type: application/vnd.company.myapp-v3+json 

Bu, HTML5 enctype özniteliğinin bir numaralandırmasıdır, buna görə bir şeydir, ancaq normal bir application/x-www-formurlencoded , multipart/form-data ve text/plain application/x-www-formurlencoded .

... və əminəm ki, HTML4-də bütün brauzerlərdə dəstəklənir (zəif bir encytpe xüsusiyyətinə malikdir, lakin MIME növü yenidən yönlendirildiyinə dair brauzerin tətbiqi ilə bağlı problem olacaq)

Buna görə də, indi versiyaya ən uyğun yol URI ilə olduğuna inanıram, amma bunun "düzgün" bir yol olmadığını qəbul edirəm.

46
13 окт. 13 oktyabrda Kevsy tərəfindən cavab verildi 2011-10-13 13:51 '11 at 13:51 pm 2011-10-13 13:51

Sürümünüzü URI-də qoyun. API-lərin bir versiyası daima növləri digərindən dəstəkləmir, belə ki resursların sadəcə bir versiyasından digərinə ötürülməsi arqumenti sadəcə yanlışdır. Bu, XML-dən JSON-a keçid kimi eyni deyildir. Tövsiyələr yox ola bilər və ya onlar semantik olaraq dəyişdirilə bilər.

Versiyalar resurs ünvanının bir hissəsidir. Bir API-dən digərinə marşrutlaşdırırsınız. Başlığı ünvanlamaq gizli deyil.

21
05 июня '12 в 18:09 2012-06-05 18:09 Cavab Sean O'Dell - ə verildi 05 İyun 2012 'at 18:09 2012-06-05 18:09

REST API-da versiyaları idarə edə biləcəyiniz bir neçə yer var:

  • URI-da qeyd edildiyi kimi. Bu yönləndirmələr, və s. Əgər qəbul edilə bilən və hətta estetik baxımdan xoş olsun. Yaxşı istifadə olunur.

  • Başlığı qəbul edir: beləliklə, versiya faylda. "Mp4" ə qarşı "mp3" kimi. Bu da işləyəcək, baxmayaraq ki, IMO daha az pis işləyir ...

  • Resursun özüdür. Bir çox fayl formatında adətən başlıqda yerləşdirilən versiya nömrələri var; bu, yeni bir proqramın dəstəklənməmiş (yenisi) versiyası göstərildikdə, köhnə proqramdan istifadə edərkən, faylın bütün mövcud versiyalarını anlayaraq "işləməyə" imkan verir. REST API-nın kontekstində, bu sizin URI-lərinizin heç vaxt dəyişməməsi deməkdir, yalnız ötürdüyünüz məlumatların xüsusi versiyasına cavabdır.

Bütün üç yanaşmanı istifadə etmək üçün səbəbləri görürəm:

  • yeni təmiz süpürgə API'larından və ya bu yanaşmanı istifadə etmək istədiyiniz əsas versiya dəyişikliklərindən istifadə etmək istəsəniz.
  • Müştərinin PUT / POST yerinə yetirməkdən əvvəl bilməsi istəsə, işləməyəcəyi və ya olmasın.
  • əgər hər şey yaxşıdırsa, müştəri işləməyəcəyini görmək üçün PUT / POST etməlidir.
13
24 окт. cavab pjz 24 oct verilir . 2011-10-24 19:39 '11 saat 19:39 'da 2011-10-24 19:39

REST API-nın versiyaları başqa hər hansı API ilə eynidır. Saytda kiçik dəyişikliklər edilə bilər, böyük dəyişikliklər tamamilə yeni bir API tələb edə bilər. Sizin üçün ən asan URL-də bir versiyanı quraşdırarkən hər dəfə sıfırdan başlamaq lazımdır. Müştəri üçün həyatın daha asan olmasını istəyirsinizsə, köhnəlmiş (daimi redirection), bir neçə versiyada resursları və s. Daha çətindir və daha çox səy tələb edir. Amma bu, REST'in "Cool URIs" -də tövsiyə etdiyi şeydir, dəyişməyin.

Sonda, hər hansı digər API dizaynı kimi görünür. Müştərilərin rahatlığına qarşı səyləri çəkin. Müştərilərinizin yeni versiyanıza necə uyğun olduğunu anlamağa imkan verən, API üçün semantik versiyanı necə istifadə etmək barədə düşünün.

8
06 марта '14 в 10:16 2014-03-06 10:16 Cavab Aleksandr Torstling tərəfindən 06.03.2014 tarixində 10:16 2014-03-06 10:16

etiketləri ilə bağlı digər suallar və ya sual