API REST. Geriausia praktika. Kaip įvesti parametrų reikšmių sąrašą kaip įvestį.

Pradėjome naują „REST“ API, ir norėjau, kad kai kurios bendruomenės prisidėtų prie geriausios praktikos, susijusios su tuo, kaip turėtume formatuoti įvesties parametrus:

Dabar mūsų API yra labai JSON orientuota (grąžina tik JSON). Aptarimas, ar norime / norime grąžinti XML, yra atskiras klausimas.

Kadangi mūsų produkcijos API yra orientuota į JSON, mes einame per kelią, kur mūsų indėliai yra šiek tiek orientuoti į JSON, ir maniau, kad tai gali būti patogu kai kuriems, bet keistiems.

Pavyzdžiui, norint gauti tam tikrą informaciją apie produktą, į kurią galima iš karto ištraukti kelis produktus, šiuo metu turime:

 http://our.api.com/Product?id=["101404","7267261"] 

Jei supaprastinsime, kaip:

 http://our.api.com/Product?id=101404,7267261 

Arba patogu įvesti JSON? Daugiau skausmo?

Galime priimti abu stilius, tačiau ar šis lankstumas iš tikrųjų sukelia daugiau painiavos ir galvos skausmo (išlaikomumas, dokumentacija ir tt)?

Sunkesnis yra atvejis, kai norime pasiūlyti sudėtingesnius išteklius. Pavyzdžiui, jei ieškodami norime leisti kelis filtrus:

 http://our.api.com/Search?term=pumas> 

Mes nebūtinai norime, kad filtrų tipai (pvz., Produkto tipas ir spalva) būtų įtraukti į tokius užklausų pavadinimus:

 http://our.api.com/Search?term=pumas> 

Kadangi mes norėjome sugrupuoti visus filtrų įvedimus.

Galų gale, ar tai tikrai svarbu? Tikėtina, kad yra tiek daug JSON komunalinių paslaugų, kad įvesties tipas tiesiog nesvarbu.

Žinau, kad mūsų „JavaScript“ klientai, priimantys „AJAX API“ skambučius, gali įvertinti JSON įėjimus, kad jų gyvenimas būtų lengvesnis.

267
08 апр. kas yra nustatyta 08 balandžio. 2010-04-08 20:22 '10, 08:22 PM 2010-04-08 20:22
@ 6 atsakymai

Žingsnis atgal

Visų pirma, REST aprašo URI kaip unikalų identifikatorių. Pernelyg daug žmonių patenka į URI struktūrą, o URI yra labiau „raminantys“ nei kiti. Šis argumentas yra lygiai taip pat juokingas, kad skambinant žmogui „Bob“ yra geriau nei paskambinti jį „Joe“ - abu pavadinimai atlieka „asmens tapatybės nustatymo“ užduotį. URI yra tik universalus unikalus pavadinimas.

Taigi, REST, akys teigia, ar ?id=["101404","7267261"] yra ramesnis nei ?id=101404,7267261 arba \Product\101404,7267261 šiek tiek nenaudingas.

Dabar sakydamas, kad daug kartų URI sukūrimas paprastai gali būti geras kitų RESTful tarnybos problemų rodiklis. Jūsų URI ir apskritai yra keletas raudonų vėliavų.

Pasiūlymai

  • Keletas to paties išteklių ir Content-Location URI

    Galime priimti abu stilius, tačiau ar šis lankstumas iš tikrųjų sukelia daugiau painiavos ir galvos skausmo (išlaikomumas, dokumentacija ir tt)?

    URI identifikuoja išteklius. Kiekvienas iš išteklių turi turėti vieną kanoninę URI. Tai nereiškia, kad negalite turėti dviejų URI, rodančių tą patį šaltinį, tačiau yra tam tikrų būdų tai padaryti. Jei nuspręsite naudoti ir JSON, ir sąrašo formatus (arba bet kokį kitą formatą), turite nuspręsti, kuris iš šių formatų yra pagrindinis kanoninis URI. Visuose atsakymuose į kitus URI, rodančius tą patį „išteklių“, turėtų būti Content-Location antraštė.

    Laikantis pavadinimo analogijos, kelių URI buvimas yra panašus į žmonių slapyvardžius. Tai yra gana priimtina ir dažnai gana patogi, tačiau jei naudoju slapyvardį, aš vis dar noriu žinoti savo vardą ir pavardę - „oficialų“ būdą kreiptis į šį asmenį. Taigi, kai kas nors paminėja pavadinimą „Nichloas Telsa“, aš žinau, kad jie kalba apie tą patį asmenį, kurį aš vadinu „Nicku“.

  • „Paieška“ jūsų URI

    Sunkesnis yra atvejis, kai norime pasiūlyti sudėtingesnius išteklius. Pvz., Jei norime ieškoti kelių filtrų ...

    Mano bendroji taisyklė yra ta, kad jei jūsų URI yra veiksmažodis, tai gali būti ženklas, kad kažkas yra išjungta. URI apibrėžia resursą, tačiau jie neturėtų nurodyti, ką darome su šiuo ištekliu. Tai HTTP darbas arba, sklandžiai, mūsų „vieno >

    Norėdami nutraukti vardo analogiją, naudojant veiksmažodį URI yra tarsi keisti asmens vardą, kai norite bendrauti su jais. Jei aš bendrauju su Bobu, Bobo vardas taps „BobHi“, kai noriu jam pasakyti „Sveiki“. Panašiai, kai norime „ieškoti“ produktų, mūsų URI struktūra neturėtų keistis iš „/ Product / ...“ į „/ Search / ...“.

Atsakymas į pradinį klausimą

  • Dėl ["101404","7267261"] vs 101404,7267261 : mano pasiūlymas yra išvengti JSON sintaksės paprastumui (t. Y. Nebūtina, kad naudotojai koduotų URL, kai to tikrai nereikia). Dėl to jūsų API taps dar patogesnė. Dar geriau, kaip kiti rekomendavo, pereikite prie standartinio application/x-www-form-urlencoded formato, nes jis tikriausiai bus labiausiai žinomas jūsų galutiniams vartotojams (pvz. ?id[]=101404> ). Tai gali būti ne „gana“, bet „Pretty URI“ nebūtinai reiškia naudojamus URI. Tačiau, norėdamas pakartoti savo pradinį tašką, galiausiai, kai kalbama apie REST, tai nesvarbu. Negalima gyventi ant jos per daug.

  • Jūsų įprastos URI paieškos pavyzdys gali būti išspręstas lygiai taip pat, kaip ir jūsų produkto pavyzdys. Norėčiau rekomenduoti grįžti į formatą „ application/x-www-form-urlencoded , nes jau yra standartas, kurį daugelis pažįsta. Be to, rekomenduoju juos sujungti.

Jūsų URI ...

 /Search?term=pumas> 

Jūsų URI po kodavimo URI ...

 /Search?term=pumas> 

Galite konvertuoti į ...

 /Product?term=pumas> 

Be to, norint išvengti URL kodavimo reikalavimo ir šiek tiek labiau standartizuoti, dabar API šiek tiek homogenizuoja. Vartotojas žino, kad jei jie nori gauti produktą ar produktų sąrašą (abu yra laikomi vieninteliais „ištekliais“ iš naujo), jie domisi /Product/... URI.

246
07 февр. Atsakymas pateikiamas 07 kategorija. 2012-02-07 15:44 '12, 15:44 pm 2012-02-07 15:44

Standartinis būdas perduoti vertybių sąrašą kaip URL parametrus yra pakartoti juos:

http://our.api.com/Product?id=101404>

Dauguma serverio kodų tai interpretuoja kaip vertybių sąrašą, nors daugelis jų turi supaprastintas reikšmes, todėl gali tekti ieškoti.

Ribotos vertės taip pat yra tvarkingos.

border=0

Jei jums reikia atsiųsti JSON į serverį, nemėgstu jo matyti URL (tai yra kitoks formatas). Visų pirma, URL turi ribinį dydį (praktiškai, jei ne teoriškai).

Kaip matiau, kai kurie iš jų atlieka sudėtingą RESTfully įvykdytą užklausą dviem etapais:

  • POST užklausos reikalavimus, gauti identifikatorių (iš esmės sukuriant paieškos kriterijų šaltinį)
  • GET ieškokite nuorodos į pirmiau nurodytą ID
  • Pasirinktinai DELETE užklausos reikalavimus, jei reikia, tačiau atkreipkite dėmesį, kad jie galimi pakartotiniam naudojimui.
140
08 апр. Kathy Van Stone atsakymas, pateiktas balandžio 8 d 2010-04-08 20:33 '10, 20:33, 2010-04-08 20:33

Pirma:

Manau, galite tai padaryti dviem būdais.

http://our.api.com/Product/<id> : jei jums reikia tik vieno įrašo

http://our.api.com/Product : jei norite visus įrašus

http://our.api.com/Product/<id1>,<id2> : kaip siūlė Džeimsas, tai gali būti pasirinktis, nes po žyma „Product“ yra parametras

Arba man labiausiai patinka:

Galite naudoti „ Hypermedia“ nuosavybę kaip „RestFul WS“ objekto taikymo būseną (HATEOAS) ir paskambinti į http://our.api.com/Product , kuris turėtų grąžinti lygiaverčius URL http://our.api.com/Product/<id> ir paskui juos paskambinkite.

Antrasis

Kai reikia skambinti URL skambučiais. Siūlyčiau naudoti HATEOAS.

1) Gauti skambutį http://our.api.com/term/pumas/productType/clothing/color/black

2) Gauti skambutį http://our.api.com/term/pumas/productType/clothing,bags/color/black,red

3) (naudojant HATEOAS). Skambinkite http://our.api.com/term/pumas/productType/ → gaukite visų galimų drabužių URL adresus → skambinkite norimais drabužiais (drabužiais ir krepšeliais) → gaukite galimus spalvotus URL tuos, kuriuos norite

15
08 апр. Atsakymas duotas Diego Dias 08 balandžio. 2010-04-08 20:53 '10, 20:53, 2010-04-08 20:53

Pirmasis atvejis:

Įprasta produkto paieška atrodys taip:

http://our.api.com/product/1

Taigi, manau, kad tai yra geriausia praktika.

http://our.api.com/Product/101404,7267261

Antrasis atvejis

Paieška su užklausų rodymo parametrais yra puiki. Norėčiau derinti terminus su AND ir OR vietoj [] .

PS Tai gali būti subjektyvus, todėl tai, kas jums patogu.

Priežastys, kodėl duomenys pateikiami į URL, yra tai, kad nuoroda gali būti įterpta į svetainę / bendrinama naudotojų. Jei tai nėra problema, naudokite JSON / POST.

EDIT: refleksija, manau, kad šis požiūris tinka subjektui su sudėtiniu raktu, bet ne kelių objektų užklausa.

6
08 апр. atsakymą pateikė Jamesas Westgate 08 balandžio. 2010-04-08 20:34 '10, 20:34, 2010-04-08 20:34

Galite sužinoti RFC 6570 . Ši URI modelio specifikacija pateikia daug pavyzdžių, kaip URL gali turėti parametrų.

6
09 апр. atsakymą pateikė Darrel Miller 09 balandžio. 2010-04-09 03:34 '10, 3:34, 2010-04-09 03:34

Sutinku su nategood atsakymu, nes jis yra baigtas, ir jis atrodė kaip jūsų poreikiai. Nors norėčiau pridurti komentarą dėl kelių (1 ar daugiau) išteklių identifikavimo šiuo būdu:

http://our.api.com/Product/101404,7267261

Su tuo jūs:

Pagerinkite klientus, verčiant juos interpretuoti jūsų atsakymą kaip masyvą, kuris yra intuityviai priešingas man, jei http://our.api.com/Product/101404 tokį prašymą: http://our.api.com/Product/101404

Sukurti nereikalingas API su viena API, kad gautumėte visus produktus ir vieną, kad gautumėte 1 ar daugiau. Kadangi neturėtumėte rodyti naudotojui daugiau nei 1 puslapio informacijos apie UX, manau, kad daugiau nei 1 identifikatorius būtų nenaudingas ir naudojamas tik produktų filtravimui.

Galbūt tai nėra taip problemiška, tačiau turėsite apdoroti šią serverio pusę, grąžinti vieną objektą (patikrinkite, ar jūsų atsakyme yra vienas ar keli), arba leisti klientams ją valdyti.

Pavyzdys

Noriu užsisakyti knygą iš nuostabios. Aš tiksliai žinau, kokia knyga, ir jį matau sąraše, kai naršote siaubo knygose:

  • 10.000 nuostabių linijų, 0 nuostabių testų
  • Nuostabi monstras grįžta
  • Leiskite dvigubo nuostabaus kodo
  • Nuostabi pabaigos pabaiga

Pasirinkus antrąją knygą, aš nukreipiu į puslapį, kuriame yra išsamus knygos dalies aprašymas:

 -------------------------------------------- Book #1 -------------------------------------------- Title: The return of the amazing monster Summary: Pages: Publisher: -------------------------------------------- 

Arba puslapyje, kuriame pateikiama visa informacija apie šią knygą?

 --------------------------------- The return of the amazing monster --------------------------------- Summary: Pages: Publisher: --------------------------------- 

Mano nuomonė

Siūlyčiau naudoti kelio kintamajame identifikatorių, kai yra užtikrinamas nedviprasmiškumas gaunant duomenis iš šio šaltinio. Pavyzdžiui, toliau pateiktos API suteikia kelis būdus, kaip gauti informaciją apie konkretų šaltinį (su sąlyga, kad gaminys turi unikalų identifikatorių, o šio produkto specifikacija turi unikalų pavadinimą ir galite pereiti iš viršaus į apačią):

 /products/{id} /products/{id}/specs/{name} 

Tuo metu, kai jums reikia daugiau nei vieno išteklių, siūlau filtruoti iš didesnės kolekcijos. Dėl to paties pavyzdžio:

 /products?ids= 

Žinoma, tai yra mano nuomonė, nes ji nėra nustatyta.

0
30 окт. atsakymas pateikiamas gumol 30 okt. 2017-10-30 22:30 '17, 10:30 val. 2017-10-30 22:30

Kiti klausimai apie žymes arba Užduoti klausimą