API REST. Ən yaxşı təcrübələr. Parametrləri harada göstərmək olar?

REST API ən azı iki şəkildə parametrlərə malik ola bilər:

  • URL yolunun bir hissəsi (yəni /api/resource/parametervalue )
  • Sorgu arqumenti (yəni /api/resource?parameter=value )

Burada ən yaxşı təcrübə nədir? 1-i və 2-dən istifadə edəcəyi zaman ümumi qaydalar varmı?

Real dünya misal: Twitter intervalları müəyyən etmək üçün sorğu parametrlərini istifadə edir. ( http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345> )

Bu parametrləri URL yolunda yerləşdirmək üçün ən yaxşı dizayn hesab olunurmu?

348
26 окт. Kalle Gustafsson tərəfindən 26 oct. 2010-10-26 16:45 '10 saat 16:45 'da 2010-10-26 16:45
@ 14 cavab

Sənədli tövsiyələr varsa, mən hələ tapmadıq. Ancaq burada bir parametrdə parametrləri müəyyənləşdirmək üçün istifadə etdiyim bəzi qaydalar var:

İsteğe bağlı parametrlər, sorgu dizgesine eklemek üçün genellikle daha kolaydır.

Parametr dəyəri mövcud bir qayana uyğun gəlmədikdə 404 səhvini qaytarmaq istəyirsinizsə, yol seqment parametrinə meylli olardım. məsələn /customer/232 burada 232 etibarlı bir müştəri identifikatoru deyildir.

Boş bir siyahı qayıtmaq istəyirsinizsə, parametr tapılmadıqda, sorgu dizesinin parametrlərini istifadə edərək gəlir. məsələn /contacts?name=dave

Parametr URI alanınızın bütün alt hissəsini təsir edərsə, bir yol segmentini istifadə edin. məsələn, /en/document/foo.txt dil parametresiyle /document/foo.txt?> ilə müqayisədə

Sorgu parametresinde deyil, yol segmentinde olmaq üçün benzersiz tanımlayıcıları tercih ederim.

URI-lər üçün rəsmi qaydalar bu RFC spesifikasiyasında. Burada URI'ların parametrləşdirilməsi qaydalarını müəyyən edən bir çox faydalı RFC spesifikasiyası mövcuddur.

254
27 окт. Darrel Millerə cavabı Oct 27. 2010-10-27 02:33 '10 saat 02:33 'da 2010-10-27 02:33

Son cavab, amma bölündüklərim haqqında əlavə məlumat verəcəyəm, yəni sorğuda bir neçə "parametr" var və bunu nəzərə almalıyıq.

  • Locators - məsələn. identifikatorlar və ya fəaliyyət / təqdimat kimi qaynaq identifikatorları
  • Filtrlər - məsələn. nəticəni müəyyənləşdirmək, sıralamaq və ya daraltmak üçün parametrlər.
  • Dövlət - məsələn. sessiyanın müəyyən edilməsi, düymələrin api, whatevs.
  • Məzmun - məsələn. saxlanılacaq məlumatlar.

İndi bu parametrlərin olduğu müxtəlif yerlərə baxaq.

  • Başlar və Cookies tələb
  • URL sorğu sətri ("GET")
  • URL'ler
  • Bədən sorgu dizesi / multipart ("POST")

Tipik olaraq, statusu məlumatın növünə görə vəziyyətin başlıqlarda və ya çerezlərdə konfiqurasiya edilməsini istəyir. Hesab edirəm ki, hamımız bu barədə razılığa gələ bilərik. Lazım gələrsə xüsusi http başlıqlarını (X-My-Header) istifadə edin.

Eynilə, məzmun sorğu xətti və ya http multipart və / və ya JSON məzmunu kimi istək orqanında olan yalnız bir yerə malikdir. Bu məzmunu göndərərkən serverdən aldığınız şey ilə uyğun gəlir. Buna görə də, siz kobud olmamalı və bunu fərqli bir şəkildə etməlisiniz.

border=0

"İd = 5" və ya "fəaliyyət = yeniləmə" və ya "səhifə = 2" kimi göstəricilər, bir URL kimi bir yola sahib olmalıdır, məsələn, mysite.com/article/5/page=2 hər bir hissəni ifadə edir (məqalə və 5 kimi əsaslar, əlbəttə ki, 5 identifikatorla yazı tipi məlumat əldə edirəm) və əlavə parametrlər URI-nın bir hissəsi kimi verilmişdir. Əgər "URI" qovluğunda müəyyən bir nöqtədən sonra cütlənmiş dəyərlər olduğunu bilirsinizsə, onlar page=2 və ya page/2 şəklində ola bilərlər.

Süzgəclər həmişə sorgu simvoluna daxil edilir, çünki onlar doğru məlumat üçün axtarışın bir hissəsidir, yalnız bir alt kümeyi və ya Locatorların tək başına qaytarılmasının faktı olduğunu bildirirlər. mysite.com/article/?query=Obama (alt qrup) bir axtarış və /article/5?order=backwards (bir dəyişiklik). O, nə etdiyinə dair düşünməyin, sadəcə nə deyirdi!

"Görünüş" çıxış formatını müəyyənləşdirirsə, bu, istədiyiniz qaydanı geri qaytarmaq deyil, tapılan mysite.com/article/5?view=pdf dəyişməsini qaytarır, çünki bir mysite.com/article/5?view=pdf ( mysite.com/article/5?view=pdf ). Əksinə, məqalənin xüsusi hissəsini ( mysite.com/article/5/view=summary ) görəcəksiniz, onda bu bir axtarış edir.

Diqqət yetirən resursların süzülməsini unutmayın. Bir mənbədə xüsusi bir şey axtarış - axtarış ... duh. Subset filtrelemesi hər hansı bir nəticə sayını (hətta 0) qoya bilər. Axtarış hər zaman bir şeyin müəyyən bir formasını (mövcud olduqda) tapacaqdır. Modifikasiya filtrelemesi, dəyişdirilmiş olanlar istisna olmaqla (əgər belə bir dəyişiklik edilsə), axtarışçı ilə eyni məlumatları qaytaracaqdır.

Ümid edirəm ki, bu, insanlara eureka nöqtələrini vermək, onlar itirildikdə, hər şeyi qoymaq üçün kömək etdi!

152
01 авг. Cavab verilir Tor Valamo 01 aug. 2013-08-01 19:12 '13 saat 07:12 'da 2013-08-01 19:12

Bu dizayndan asılıdır. HTTP-də REST-də URI-lər üçün heç bir qaydalar yoxdur (əsas odur ki, onlar unikaldır). Tez-tez dad və intuisiya məsələsinə aiddir ...

Aşağıdakı yanaşmanı istifadə edirəm:

  • URL: resurs və onun yol elementi directory traversal və sub-resource təşkil edir (məsələn, / items / {id}, / users / items). Etibarsız olduğunuzda, yoldaşları bir yol açmağı düşünsələr və "fərqli bir kataloq" deyə düşünsələr, yolun ən çox ehtimal olunan elementi doğru seçimdir.
  • Url parametri: bir tarama olmadan (birdən çox sorğu parametrləri olan axtarış resursları bunun üçün çox yaxşı bir nümunədir)
21
26 окт. 26 avqust manuel aldana tərəfindən verilmiş cavab . 2010-10-26 21:00 '10 saat 21:00 'da, 2010-10-26 21:00' de

IMO parametrləri sorgu argümanları olaraq daha yaxşı olmalıdır. URL resursu müəyyən etmək üçün istifadə olunur, əlavə sorgu parametrləri istədiyiniz qaynağın hansı hissəsini, qaynaqın hansı vəziyyətdə olacağını müəyyən edir və s.

18
26 окт. PeterWong tərəfindən verilmiş cavab 26 oktyabr 2010-10-26 16:52 '10 at 16:52 2010-10-26 16:52

RESTin tətbiqinə uyğun olaraq,

1) Yol dəyişənləri əlaqə və ya mahnı kimi qaynaqlar kimi birbaşa fəaliyyət üçün istifadə olunur.
GET etc / api / resource / {songid} və ya
GET etc / api / resource / {contactid} müvafiq məlumatları qaytarır.

2) Perm / argument sorgusu, mahnıların metadata ex., GET / api / resource / {songid} kimi daxili resurslar üçün istifadə olunur? Metadata = janrlar bu xüsusi mahnı üçün janr məlumatlarını qaytarır.

17
26 окт. Şeytan Bellapu cavab 26 Oct 2012-10-26 23:25 '12 də 23:25 2012-10-26 23:25

"Paket" və məlumatlarınızı kainat-resurs-axtarışçı təmin edən "kontekstə" qarşı POST, yəni axtarış üçün # 1 deməkdir.

C # -in məhdudiyyətlərinə diqqət yetirin. Mən # 1-in POST-lərini üstün tuturam.

Qeyd: məhdudiyyətlər müzakirə olunur

POST in POST parametrinin məzmunu üçün maksimum ölçüsü varmı?

GET in GET tələbinin uzunluğu üzrə bir limit varmı?_GET-də URL parametrlərinin maksimum ölçüsü

ps bu məhdudiyyətlər müştəri imkanlarına (brauzer) və serverə (konfiqurasiya) əsaslanır.

16
26 окт. Cavab 26 aylıq cavab verilir . 2012-10-26 15:04 '12 at 3:04 pm 2012-10-26 15:04

URI standartına uyğun olaraq , yol iyerarxik parametrlər üçün nəzərdə tutulmuşdur və sorgu hiyerarxik olmayan parametrlər üçündür. Ofc. sizin üçün hiyerarşik olan çox subyektiv ola bilər.

Birdən çox URI-lərin eyni resursa verildiyi hallarda istəkdə istəkdə parametrləri - görünmə üçün lazım olan yol və parametrlərdə - müəyyənləşdirilməsi üçün lazım olan parametrləri yerləşdirmək istərdim. (Bu yol mənim üçün daha asandır.)

Məsələn:

  • /users/123/users/123?fields="name, age"
  • /users/users?name="John">

Xəritəni azaltmaq üçün aşağıdakı yanaşmaları istifadə etmək istərdim:

  • /users?name="John">
  • /users/name:John/age:30

Belə ki, həqiqətən (və server yönlendiricinizə) URI-lərinizi necə yaratdığınızı.

Qeyd Bu parametrləri, sorğu parametrlərini qeyd etmək. Beləliklə, nə etdiyinizi sadə bir sorğu dilini müəyyən edir. Mürəkkəb sorgular (və ya daha çox və ya daha çox operatorları olan) istifadə edərək mövcud sorgu dilini istifadə etməyi məsləhət görürəm. URI şablonu xüsusiyyətləri çox məhduddur ...

5
20 сент. cavab inf3rno 20 sep verilir . 2014-09-20 01:12 '14 da 1:12 2014-09-20 01:12

Heç bir sərt və sürətli qaydalar yoxdur, amma istifadə etmək istəməyimə dair tamamilə konseptual baxımdan başqalarının qayğısı aşağıdakı kimi qısaca yekunlaşdırıla bilər: URI yolunun (müəyyənləşdirmə ilə) qaynağı təmsil edir və istək parametrləri əsasən bu resursda dəyişənlərdir. İndiyə qədər bu kömək etmək çətin deyil ... REST API ilə, GET , PUTDELETE istifadə edərək bir qayda ilə işləmək üçün əsas metodlarınız var. Buna görə, bu metodlar sözügedən təmsilçilik üçün mənalı olsun ki, bir şəkildə və ya bir parametr kimi təmin edilməlidir. Siz yol boyunca bir PUT və bu, semantik cəhətdən sərin olardı? Əlbəttə ki, demək olar ki, heç bir yerdə PUT bir şey edə bilərsiniz və onu emal etmək üçün arxa əymək olar, ancaq faktiki qaynağın təmsil olunması deyil, bəzi lazımsız kontekstləşməmiş versiyasıdır. Koleksiyonlar üçün eyni POST ilə edilə bilər. URL'nin POST a aid olduğu xüsusi bir kolleksiyaya əlavə etmək istəyirsinizsə.

Bəzi yollar valideyn qaynaqlarının neçə uşaqının bir qədər seçici və istifadə olunmalarından asılı olduğunu göstərə bilər, çünki bu hələ də bəzi boz sahələri tərk edir. Çəkdiyimiz bir sərt xətt, əsas qaynaqa malik olmadığı üçün, hər hansı növ keçid təqdimatının sorğu parametrindən istifadə edilməsidir.

Orijinal sualda (Twitter API) verilən real-dünya misalına cavab olaraq, parametrlər resursların vəziyyətini (hierarxiya deyil) filtreleyen keçidli bir sorğudur. Bu xüsusi nümunədə, bu məhdudiyyətlərdən ibarət olan kolleksiyaya əlavə etmək tamamilə əsassız olardı və üstəlik, bu sorgu obraz obyekti baxımından heç bir məna daşımayan bir yol kimi təqdim edilə bilməzdi.

Bu cür resurs yönümlü perspektivi qəbul etmək asanlıqla domen modelinizin obyektinin qrafikinə birbaşa eşlenip API'nızın mantığını idarə etmək üçün hər şey hər bir işdə çox təmiz və kifayət qədər özünü sənədləşdirən şəkildə aydınlıqla işlədilir. Anlayış, adətən normal olaraq zəif uyğun olan məlumat modelinə (yəni, RDBMS) təsvir edilən ənənəvi URL marşrutlaşdırma sistemlərini istifadə edən sistemlərdən geri çəkilərək daha aydın ola bilər. Apache Sling mütləq başlamaq üçün yaxşı bir yer olacaq. Zope- tipli bir sistemdə bir tarama obyekti göndərmək konsepsiyası daha aydın bir tərəfdaş təmin edir.

4
26 окт. Matt Whipple tərəfindən verilmiş cavab 26 oktyabr. 2012-10-26 15:21 '12 at 15:21 2012-10-26 15:21

Mənim fikrimdir.

Sorgu parametreleri sorgu üçün metadata olaraq istifadə olunur. Mövcud resurs çağırışı üçün bir filtre və ya modifier kimi çıxış edirlər.

Məsələn:

/calendar/2014-08-08/events

o gün üçün təqvim hadisələrini təmin etməlidir.

Müəyyən bir kateqoriya üçün hadisələrə ehtiyacınız varsa

/calendar/2014-08-08/events?category=appointments

30 dəqiqə ərzində hadisələrə ehtiyacınız varsa

/calendar/2014-08-08/events?duration=30

Litmus testi, istək parametrləri olmadan istənilən xidmətin veriləcəyini yoxlayacaq.

4
15 авг. Cavab 15 dekabrda Jay tərəfindən verilir . 2014-08-15 00:59 '14 'də 0:59 2014-08-15 00:59

Müştəri tərəfində tez-tez bir proqramçı olaraq, mən sorğu arqumentini üstün edirəm. Bundan əlavə, mənim üçün URL'yi parametrlərdən ayırır, aydınlıq gətirir və daha genişlənənlik təklif edir. Həmçinin URL / URI binası ilə parametrik konstruktor arasında ayrı məntiqə sahib olmağıma da imkan verir.

Manuel Aldanın başqa bir versiya haqqında söylədiyini xoşlayıram, əgər bir növ ağac varsa. Görürəm ki, istifadəçiyə aid xüsusi məlumatlar bu kimi görünür.

4
25 окт. Joe Plante tərəfindən 25 Oktyabrda verilən cavab 2012-10-25 23:51 '12 at 11:51 PM 2012-10-25 23:51

Ümumiyyətlə, sorğu arqumenti (yəni / api / resource = parametr = dəyər) kimi # 2'ye doğru yalvarıram.

Üçüncü variant parametr dəyərini əslində bədənə göndərməkdir.

Bu, bir neçə parametri olan resurslar üçün daha yaxşı işlədiyindən və gələcəkdə istifadə üçün daha genişlənməsindən asılıdır.

Hansı birini seçdiyinizdən asılı olmayaraq, yalnız bir seçdiyinizə əmin olun, qarışdırmayın və ya eşleşməyin. Bu bir obfuscating API gətirib çıxarır.

2
26 окт. cavab NorthIsUp 26 oct verilir . 2010-10-26 21:05 '10 at 21:05 2010-10-26 21:05

Bu mövzunun bir "ölçüsü" silindi, lakin çox vacibdir: "ən yaxşı təcrübələr" REST imkanları ilə tətbiq olunan və ya tamamlayan tavanla müqavilələrə daxil olmağı tələb edən hallar var.

Praktiki nümunə:

Hal-hazırda, bir çox web applications MVC memarlıq həyata (model, görünüşü, nəzarətçi) həyata keçirir. Xüsusilə bu web tətbiqləri "SEO URL'lərini daxil et" seçimi ilə gəldikdə müəyyən bir standart yolu təklif edirlər.

Yalnız kifayət qədər tanınmış bir web tətbiqindən söz edin: E-ticarət mağazası OpenCart. Bir yönetici "SEO URL'lerini" çözdüğünde, belirtilen URL'lerin standart MVC biçiminde kullanılmasını bekler, məsələn:

 http://www.domain.tld/special-offers/list-all?limit=25 

Harada?

  • special-offers URL'yi işləyən MVC nəzarətçi (xüsusi təkliflər səhifəsini göstərmək)

  • list-all nəzarətçi adı və ya zəng etmək üçün funksiyanın adıdır. (*)

  • limit = 25 - səhifədə 25 elementin göstəriləcəyini göstərən variant.

(*) list-all mən aydınlıq üçün istifadə edilən saxta funksiya adıdır. Əslində, OpenCart və ən çox MVC çərçivələri istifadəçi default tədbiri yerinə yetirmək istədikdə çağırılan bir nəzərdə tutulmuş (və URL adətən atılan) bir index funksiyası var. Beləliklə, real dünya URL'si:

 http://www.domain.tld/special-offers?limit=25 

Yuxarıda göstərilənlərə bənzər bir standart tətbiq və ya çərçivə strukturu ilə, tez-tez bunun üçün URL-lərin rewrites (real "SEO olmadan URL" olacaq) üçün optimize bir web server almaq: http://www.domain.tld/index.php?route=special-offers/list-all> ).

Buna görə də, bir geliştirici olaraq, mövcud infrastrukturla işləmək və "ən yaxşı təcrübələri" uyğunlaşdırmaqla qarşılaşırsınız, əgər sistem administratoru olmadıqda, Apache / NGinx konfiqurasiyanın yenidən qurulmasını (sonuncusu pis ola bilər!), Etc.

Beləliklə, SİZİN REST API'sı tez-tez göndərilən veb tətbiqi standartlarına riayət etmək üçün, həm də bununla uyğunluq təmin etmək üçün və rahatlıq / sürət üçün (və buna görə də büdcəni qorumaq üçün) daha yaxşı olacaq.

Yuxarıdakı praktiki nümunəyə qayıtmaq üçün ardıcıl REST API kimi URL'leri ilə olacaq:

 http://www.domain.tld/api/special-offers-list?from=15> 

və ya (qeyri SEO URL)

 http://www.domain.tld/index.php?route=api/special-offers-list?from=15> 

arqumentlərin və "yaranan sorğuların" "yaradılan yolları" nın birləşməsi ilə.

2
03 июля '14 в 14:52 2014-07-03 14:52 cavab Dario Fumagalli tərəfindən 03.07.2014 tarixində 14:52 2014-07-03 14:52 verilir

Parametrləri yaxşı idarə etməyən bir çox REST API-ni görürəm. Tez-tez ortaya çıxan bir nümunə, bir URI şəxsi məlumatı ehtiva edir.

http://software.danielwatrous.com/design-principles-for-rest-apis/

Mən düşünürəm ki, istintaq məsələsi parametrenin heç bir parametr olmamasıdır, amma əvəzinə HEADER ya BODY tələbinə köçürülməlidir.

1
12 авг. Daniel Watrous tərəfindən verilmiş cavab 12 Avqust. 2014-08-12 19:40 '14 at 19:40 2014-08-12 19:40

Bu çox maraqlı bir sual.

Bunlardan hər ikisini də istifadə edə bilərsiniz, bu barədə heç bir ciddi qaydalar yoxdur, lakin URI yol dəyişənləri istifadə edərək bir sıra üstünlüklərə malikdir:

  • Cache: İnternetdə bir çox veb önbellek xidməti, istek parametreleri içerdiğinde, GET isteğini önbelleğe almaz. Onlar serverdə məlumatları dəyişdirmək üçün GET-in istifadələrini istifadə edən bir çox RPC sisteminin olduğu üçün onlar bunu edirlər (təhlükəsiz bir metod olmalıdır)

Değişken yolları kullanırsanız, bu hizmetlerin hepsi GET isteklerinizi önbelleğe ala bilər.

  • Hiyerarşi: Dəyişən yollar hiyerarşiyi təmsil edə bilər: / Şəhər / Küçə / Yeri

İstifadəçi məlumat strukturu haqqında əlavə məlumat verir.

Lakin məlumatlarınız hiyerarşiyə aid deyilsə, hələ də virgül və ya virgüllə istifadə edilən Yol dəyişənləri istifadə edə bilərsiniz:

/ Şəhər / Boylam, enlem

Tipik olaraq parametrlər sifariş edərkən bir vergül istifadə edin, sifariş etmədikdə virgül istifadə etməz:

/ IconGenerator / qırmızı, mavi, yaşıl

Bu səbəblərə əlavə olaraq, sorgu dizesi değişkenlerinin sıkça kullanıldığı bazı durumlar vardır:

  • HTML form dəyişənlərini avtomatik olaraq URI-də yerləşdirmək üçün brauzerə ehtiyacınız olduqda
  • Bir alqoritmlə məşğul olduğunuzda. Məsələn, google mühərriki sorğu sətrlərini istifadə edir:

http://www.google.com/search?q=rest

Xülasə etmək üçün bu metodlardan birini istifadə etmək üçün yaxşı bir səbəb yoxdur, lakin mümkün olduqda, URI dəyişənləri istifadə edin.

0
13 февр. Cavab 13 fevral tarixində jfcorugedo tərəfindən verilir . 2015-02-13 12:12 '15 'da 12:12' de 2015-02-13 12:12

bağlı digər suallar və ya sual soruşun