WebAPI の設計

2021-12-04、2022-03-18の1DayインターンでLTした内容です

Transcript

1. WebAPIͷઃܭ Yumemi 1DayΠϯλʔϯ 2022/03/18 @sun-yryr / גࣜձࣾΏΊΈ
2. ΏΔΏΔ / Taiyo Minagawa w 
   גࣜձࣾΏΊΈ
   ৽ଔೖࣾ
   w 4FSWFSTJEF
   &OHJOFFS
   ΍ͬͯ·͢ɻ ܦྺ ޷͖ͳ͜ͱ w 4XJGU
   4FSWFSTJEF
   $*$%
   w 75VCFS sun-yryr taittide taittide sunyryr 
3. ࢀߟਤॻ  λΠτϧ: Web API: The Good Parts ൃߦ: O'Reilly Ձ֨: ෺ཧຊ ¥2420 ిࢠຊ ¥1936
4. ໨࣍ • ඒ͍͠WebAPI • URLઃܭͷϙΠϯτ • WebAPIઃܭͷํ਑ • Q&A 
5. ඒ͍͠WebAPI 
6. WebAPI • API => Application Programming Interface • HTTPϓϩτίϧΛ࢖ͬͯ֎෦ϦιʔεͷػೳΛݺͼग़͢ • ؔ਺ͷΑ͏ͳ΋ͷ 
7. “ඒ͍͠”ʁ • ୭ʹͱͬͯ΋࢖͍΍͍͢͜ͱ • มߋ͠΍͍͢͜ͱ • ੬ऑੑʹରͯ͠ؤڧͰ͋Δ͜ͱ • ஏ͔ͣ͘͠ͳ͍͜ͱ 
8. ඒ͍͠WebAPIΛ࡞ΔͨΊʹେ੾ͳ͜ͱ • RFCͳͲͷ࢓༷͕͋Δ৔߹͸ͦΕʹै͏͜ͱ • ࢓༷͕ͳ͍৔߹͸σϑΝΫτελϯμʔυʹै͏͜ͱ • ଞͷ༗໊APIΛࢀߟʹ͢Δ 
9. URLઃܭͷϙΠϯτ 
10. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
11. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
12. ୹͍URL • ೖྗ͠΍͘͢ɺ֮͑΍͍͢ͷͰྑ͍  × http://api.example.com/api/v1/users/ " api͕υϝΠϯ෦෼ͱύε෦෼Ͱඃ͍ͬͯΔ ◦ http://api.example.com/v1/users/
13. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
14. ਓ͕ؒཧղͰ͖ΔURL • ਪଌ͠΍͍͢ɺԿ͕ى͜Δ͔෼͔Γ΍͍͢ • ೔ຊޠͳͲ͸Τϯίʔυ͞Εͯ͠·͍෼͔ΓͮΒ͘ͳΔͨΊɺ ආ͚ͨํ͕ྑ͍  × http://api.example.com/u/d/ " u΋d΋ҙຯ͕Θ͔Βͳ͍ɻ୹͚Ε͹୹͍΄Ͳྑ͍Θ͚Ͱ͸ͳ͍ɻ ◦ http://api.example.com/users/detail/
15. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
16. খจࣈͷΈͷURL • େจࣈ͕ࠞࡏ͢ΔͱΘ͔ΓͮΒ͘ͳΔ • ϗετ෦͸େจࣈ͕ແࢹ͞ΕΔ࢓༷͕͋ΔͨΊɺͦΕʹै͏  × http://api.example.com/Users/Detail " ϑΥϯτʹΑͬͯ͸େจࣈখจࣈ͕Θ͔ΓͮΒ͍ɻಛʹIͱlͳͲ ◦ http://api.example.com/users/detail/
17. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
18. αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍URL • ಺෦࣮૷͸஌ΒΕͳ͍ํ͕ηΩϡϦςΟతʹ΋˓  × http://api.example.com/cgi-bin/users.php " CGI൛ͷPHPͬΆ͍ͳͱΘ͔ͬͯ͠·͏ ◦ http://api.example.com/users/
19. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • ߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
20. ߏ଄͕౷Ұ͞Ε͍ͯΔURL • ౷Ұ͞Ε͍ͯΔͱ෼͔Γ΍͢͞ʹͭͳ͕Δ  × http://api.example.com/users/123/ Ϣʔβʔ৘ใৄࡉ × http://api.example.com/users/friends?user_id=123 ࢦఆͨ͠Ϣʔβʔͷ༑ୡҰཡ " ্͸ύεύϥϝʔλͰɺԼ͸ΫΤϦύϥϝʔλͱҰ؏ੑ͕ͳ͍ ◦ http://api.example.com/users/123/ ◦ http://api.example.com/users/123/friends/
21. • ୹͍ • ਓ͕ؒಡΜͰཧղͰ͖Δ • খจࣈͷΈ • αʔόʔͷ࣮૷ʹґଘͯ͠ͳ͍ • URLߏ଄͕౷Ұ͞Ε͍ͯΔ • HTTPϝιου͕نఆʹԊ͍ͬͯΔ 
22. HTTPϝιου͕نఆʹԊ͍ͬͯΔ • ࢓༷ʹै͏ • GETͰߋ৽͠ͳ͍ͳͲ  (&5 ৘ใΛऔಘ͢Δ 1045 ৽͍͠৘ใΛొ࿥͢Δ 165 ࢦఆͨ͠63-ʹ৘ใΛొ࿥͢Δ
    ৘ใΛ্ॻ͖͢Δ 1"5$) 165ʹࣅ͍ͯΔ
    ৘ใͷҰ෦Λߋ৽͢Δ %&-&5& ࢦఆͨ͠৘ใΛ࡟আ͢Δ
23. WebAPIઃܭͷਐΊํ 
24. 1. ػೳͷҰཡΛ࡞੒͢ΔʢϢʔεέʔεͷ࡞੒ʣ 2. Ϣʔεέʔε͝ͱʹඞཁͳAPIΛߟ͑Δ 3. 2Ͱߟ͑ͨඞཁͳAPIʹରͯ͠ɺHTTP Method, URL, ϦΫΤε τͷཁૉ΍ϨεϙϯεΛܾΊ͍ͯ͘ 
25. Q&A 
26. ໊ࢺ͸୯਺ܥʁෳ਺ܗʁ • αʔϏεʹΑͬͯ୯਺ͩͬͨΓෳ਺ͩͬͨΓ͢Δ • جຊతʹू߹Λද͢΋ͷ͸ෳ਺ܗ͕ద੾ͱ͞Ε͍ͯΔ • ςʔϒϧ໊΋େମෳ਺ܗͳͷͰἧ͑Δͱ෼͔Γ΍͔ͬͨ͢Γ΋ ͢Δ 
 ʢ˞ςʔϒϧͱશ͘ಉ͡ΤϯυϙΠϯτΛ༻ҙ͢Δ͚ͩ͸✖ʣ 
27. ಈࢺ͸࢖ͬͯ͸μϝʁ • ઈରͰ͸ͳ͍ • searchͳͲͷಈࢺΛ࢖͍ͬͯΔαʔϏε΋͋Δ • ͨͩɺHTTPMethodͰදͤΔ”GET”ͳͲ͸࢖Θͳ͍ํ͕ྑ͍ 
28. ୯ޠͷ࿈݁͸ʮ-ʯʁʮ_ʯʁ • ͲͪΒ͔ยํͰ౷Ұ͢Ε͹ྑ͍ • SEOతʹ͸ϋΠϑϯͷํ͕ྑ͍͕ɺWebAPIʹ͸ؔ܎ͳ͍ • Ξϯμʔόʔ͸ϦϯΫදهͷԼઢͱඃΔ͜ͱ͕͋ΔͷͰɺϋΠ ϑϯΛ͓͢͢Ί͍ͨ͠ 
29. ΫΤϦͱύεͷ࢖͍෼͚ • URL͸ϦιʔεΛද͢΋ͷͰ͋ΔͨΊɺҰҙʹܾ·Δ΋ͷͰ͋ Ε͹ύεʹؚΊͨํ͕ྑ͍ʢྫ: ϢʔβʔIDʣ • লུͰ͖Δ΋ͷ͸ΫΤϦʹ͢Δͱྑ͍ʢྫ: ҰཡऔಘͷߜΓࠐ Έ৚݅ʣ 
30. ඞͣ൚༻తʹ͢Δඞཁ͸ͳ͍ • ޿͘ެ։ͤͣɺࣗ෼ΒͰดͨ͡APIͷ৔߹͸൚༻తʹ͢Δ͜ͱͰ ͔͑ͬͯ࢖͍ͮΒ͘ʢ=Ԛ͘ʣͳͬͯ͠·͏͜ͱ͕͋Δ • ྫ͑͹ɺτοϓϖʔδʹඞཁͳ͢΂ͯͷ৘ใΛ1౓ʹฦ͢APIΛ ࡞ͬͯ΋͍͍ • ϢʔεέʔεΛେࣄʹͯ͠ઃܭ͍ͯ͘͠ͱྑ͍ 
31. OpenAPIʹ͍ͭͯগ͠ 
32. OpenAPI / Swaggerͱ͸ • REST APIͷهड़ϑΥʔϚοτ • yaml or jsonͰهड़Ͱ͖Δ • όʔδϣϯ2·Ͱ͸Swaggerͱݺ͹Ε͍͕ͯͨɺݱࡏ͸OpenAPI ͱݺ͹Ε͍ͯΔ • ݱࡏόʔδϣϯ3 
33. 
34. ࣗ෼͕ਪͤΔઃܭΛ໨ࢦͯ͠ ؤு͍ͬͯͩ͘͞