yumemi-1day-intern-web-api-design

Transcript

1. WebAPIͷઃܭ Yumemi 1DayΠϯλʔϯ 2021/12/04 @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ઃܭͷํ਑ • ʢOpenAPIʹ͍ͭͯͪΐͬ͜ͱʣ 

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. ໊ࢺ͸୯਺ܥʁෳ਺ܗʁ • αʔϏεʹΑͬͯ୯਺ͩͬͨΓෳ਺ͩͬͨΓ͢Δ • جຊతʹू߹Λද͢΋ͷ͸ෳ਺ܗ͕ద੾ͱ͞Ε͍ͯΔ • ςʔϒϧ໊΋େମෳ਺ܗͳͷͰἧ͑Δͱ෼͔Γ΍͔ͬͨ͢Γ΋ ͢Δ 

26. ಈࢺ͸࢖ͬͯ͸μϝʁ • ઈରͰ͸ͳ͍ • searchͳͲͷಈࢺΛ࢖͍ͬͯΔαʔϏε΋͋Δ • ͨͩɺHTTPMethodͰදͤΔGETͳͲ͸࢖Θͳ͍ํ͕ྑ͍ 

27. ୯ޠͷ࿈݁͸ʮ-ʯʁʮ_ʯʁ • ͲͪΒ͔ยํͰ౷Ұ͢Ε͹ྑ͍ • SEOతʹ͸ϋΠϑϯͷํ͕ྑ͍͕ɺWebAPIʹ͸ؔ܎ͳ͍ • Ξϯμʔόʔ͸ϦϯΫදهͷԼઢͱඃΔ͜ͱ͕͋ΔͷͰɺϋΠ ϑϯΛ͓͢͢Ί͍ͨ͠ 

28. ΫΤϦͱύεͷ࢖͍෼͚ • URL͸ϦιʔεΛද͢΋ͷͰ͋ΔͨΊɺҰҙʹܾ·Δ΋ͷͰ͋ Ε͹ύεʹؚΊͨํ͕ྑ͍ʢྫ: ϢʔβʔIDʣ • লུͰ͖Δ΋ͷ͸ΫΤϦʹ͢Δͱྑ͍ʢྫ: ҰཡऔಘͷߜΓࠐ Έ৚݅ʣ 

29. ඞͣ൚༻తʹ͢Δඞཁ͸ͳ͍ • ޿͘ެ։ͤͣɺࣗ෼ΒͰดͨ͡APIͷ৔߹͸൚༻తʹ͢Δ͜ͱͰ ͔͑ͬͯ࢖͍ͮΒ͘ʢ=Ԛ͘ʣͳͬͯ͠·͏͜ͱ͕͋Δ • ྫ͑͹ɺτοϓϖʔδʹඞཁͳ͢΂ͯͷ৘ใΛ1౓ʹฦ͢APIΛ ࡞ͬͯ΋͍͍ • ϢʔεέʔεΛେࣄʹͯ͠ઃܭ͍ͯ͘͠ͱྑ͍ 

30. OpenAPIʹ͍ͭͯগ͠ 

31. OpenAPI / Swaggerͱ͸ • REST APIͷهड़ϑΥʔϚοτ • yaml or jsonͰهड़Ͱ͖Δ

    • όʔδϣϯ2·Ͱ͸Swaggerͱݺ͹Ε͍͕ͯͨɺݱࡏ͸OpenAPI ͱݺ͹Ε͍ͯΔ • ݱࡏόʔδϣϯ3 

32. 

33. ࣗ෼͕ਪͤΔઃܭΛ໨ࢦͯ͠ ؤு͍ͬͯͩ͘͞