API Meetup #15

Open API Specification を使ったスマートな API 運用

Transcript

1. © 2016 KUFU, Inc.
   0QFO"1*4QFDJpDBUJPOΛ࢖ͬͨ
   εϚʔτͳ"1*ӡ༻
   גࣜձࣾ,6'6
   ۔ᖒխਓ
   ೥݄೔
   "1*.FFUVQ
   

   View Slide

2. © 2016 KUFU, Inc.
   ࣗݾ঺հ
   ۔ᖒ խਓ
   @masato_serizawa
   • גࣜձࣾ KUFU ΤϯδχΞ
   • ΤϯδχΞͱͯ͠ͷΩϟϦΞͷ΄ͱΜͲΛ WebAPI ͷઃܭɾ
   ։ൃɾӡ༻ɾൢചΛͯ͠ա͍ͯ͝͠·͢
   • ͨ·ʹ Hackathon ʹग़ͨΓ͠·͢
   • झຯ͸ Data Visualization Ͱ͢
   

   View Slide

3. ຊ೔͓࿩͢Δ͜ͱʰ8FC"1*࢓༷ॻͷӡ༻ʱ
   

   View Slide

4. © 2016 KUFU, Inc.
   ΞδΣϯμ
   •๻͕ࠓ·ͰؔΘ͖ͬͯͨ WebAPI ͱͦͷ՝୊
   •OpenAPI Specification ͕ղܾͯ͘͠ΕΔ͜ͱ
   •OpenAPI Specification ͷ࣮ફ
   •·ͱΊ
   

   View Slide

5. ๻͕ࠓ·ͰؔΘ͖ͬͯͨ
   8FC"1*ͱͦͷ՝୊
   

   View Slide

6. © 2016 KUFU, Inc.
   WebAPI ͷӡ༻ʢ։ൃҎ֎ʣ
   •WebAPI ʹ͸ I/F ࢓༷ॻ΍ϦΫΤεταϯϓϧ
   ͕෇͖΋ͷͰ͢
   •ઃܭɾ࣮૷ʹൺ΂Δͱܰࢹ͞Ε͕ͪͰ͕͢ɺར
   ༻ऀͷ UX ʹେ͖͘ӨڹΛ༩͑Δ෦෼Ͱ΋͋Γ
   ·͢
   •ͦΕΒʹ͍ͭͯɺաڈʹܞΘͬͨ WebAPI ͔Β
   ๻ֶ͕Μͩ՝୊΍ཧ૝૾Λ͓఻͑͠·͢
   

   View Slide

7. $BTFᴈ໌ظͷ8FC"1*
   

   View Slide

8. © 2016 KUFU, Inc.
   Case1: ᴈ໌ظͷ WebAPI
   ػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD
   ࣮૷೥୅ ೥୅ॳ಄
   ࣮૷ݴޠ +BWB
   ར༻
   ϑϨʔϜϫʔΫ
   ಛʹͳ͠
   Ϩεϙϯεܗࣜ 9.-
   *'࢓༷ॻ 8PSE
   جຊεϖοΫ
   

   View Slide

9. © 2016 KUFU, Inc.
   Case1: ᴈ໌ظͷ WebAPI
   •ϦΫΤεταϯϓϧ͕๛෋ʹ͋ͬͨ
   •HTML Ͱॻ͔Ε͍ͯͯɺϦϯΫΛԡ͢ͱϨεϙ
   ϯε͕֬ೝͰ͖Δ
   •ͲͷΑ͏ͳϦΫΤετύϥϝʔλ͕͋ͬͯɺͲ
   ͷΑ͏ͳϨεϙϯε͕͋Δͷ͔͕֬ೝ͠΍͍͢
   •ͪΐͬͱͨ͠ςετπʔϧʹ΋ͳΔ
   (PPE
   

   View Slide

10. © 2016 KUFU, Inc.
    Case1: ᴈ໌ظͷ WebAPI
    •࢓༷ॻ͕͋·Γӡ༻͞Ε͍ͯͳ͔ͬͨ
    •ࣾ಺ϑΝΠϧڞ༗αʔόͷͲ͔͜ʹ͋Δ Word
    •هࡌͷൈ͚࿙Ε͕໨ཱͭ
    •࣮૷Λ֬ೝͨ͠ํ͕ૣ͍…
    •࢓༷ͷ໰͍߹Θ͕ͤࡴ౸͢Δ
    1SPCMFN
    

    View Slide

11. © 2016 KUFU, Inc.
    Case1: ᴈ໌ظͷ WebAPI
    •࢓༷ॻ͕͔ͬ͠Γ͍ͯ͠ͳ͍ͱ։ൃίετ͚ͩ
    Ͱͳ͘ίϛϡχέʔγϣϯίετ΋๲Ε্͕Δ
    •ઃܭࢥ૝ͷෆ౷Ұ΋ى͖΍͍͢
    •ʢ࢓૊ΈԽ͠ͳ͍ͱʣਓ͸࢓༷ॻΛ੔උ͠ͳ͍
    •WebAPI ͸ϒϥ΢β্ͰαΫͬͱϨεϙϯε
    νΣοΫͰ͖ΔͱḿΔ
    ๻ֶ͕Μͩ͜ͱ
    

    View Slide

12. $BTFͪΐͬͱϞμϯͳ8FC"1*
    

    View Slide

13. © 2016 KUFU, Inc.
    Case2: ͪΐͬͱϞμϯͳ WebAPI
    ػೳ
    εϙοτݕࡧɺॅॴݕࡧɺFUD
    ʢલड़"1*ͷϑϧεΫϥονϓϩμΫτʣ
    ࣮૷೥୅ ೥ࠒ
    ࣮૷ݴޠ +BWB
    ར༻
    ϑϨʔϜϫʔΫ
    ಺੡8"'
    Ϩεϙϯεܗࣜ +40/
    *'࢓༷ॻ 4QIJOY
    جຊεϖοΫ
    

    View Slide

14. © 2016 KUFU, Inc.
    Case2: ͪΐͬͱϞμϯͳ WebAPI
    •I/F ࢓༷ॻΛ Sphinx Ͱ࡞੒͍ͯͨ͠
    •هड़ݴޠ͸ rstʢreStructruedTextʣ
    •ιʔείʔυͱಉ͡ϦϙδτϦͰ؅ཧ
    •ϨϏϡʔର৅ͱͳΔͨΊɺൈ͚࿙Ε͕গͳ͍
    •HTML ΍ PDF ʹม׵Ͱ͖ΔଞɺσβΠϯ΋બ
    ΂ͯඒ͍͠υΩϡϝϯτʹ࢓্͕Δ
    (PPE
    

    View Slide

15. © 2016 KUFU, Inc.
    Case2: ͪΐͬͱϞμϯͳ WebAPI
    •࢓༷ॻͷӡ༻ίετ͕গͳ͔Β͔͔ͣͬͨ
    •ΤϯυϙΠϯτΛ௥Ճ͢Δ࣌ͳͲ͸݁ߏͳίϐ
    ϖ࡞ۀ…
    •ϨεϙϯεαϯϓϧΛషΓ෇͚Δͷେม…
    •ΤϯλʔϓϥΠζ޲͚ʹผͰ࢓༷ॻΛ༻ҙ͢Δ
    Α͏ͳ৔߹͸ɺΠν͔Βॻ͖௚͢ඞཁ͕͋ͬͨ
    1SPCMFN
    

    View Slide

16. © 2016 KUFU, Inc.
    Case2: ͪΐͬͱϞμϯͳ WebAPI
    •៉ྷͳ࢓༷ॻΛ࡞Δͱت͹ΕΔ
    •৺ͳ͔͠໰͍߹Θͤ΋༑޷తͳ΋ͷʹͳΔؾ͕
    ͢Δ
    •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍
    •࢓༷ॻ͸৭ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱḿ
    Δ
    •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱศརͦ͏
    ๻ֶ͕Μͩ͜ͱ
    

    View Slide

17. ·ͱΊΔͱʜ
    

    View Slide

18. © 2016 KUFU, Inc.
    ·ͱΊ
    •ਓ͸࢓༷ॻΛ੔උ͠ͳ͍
    •ϨεϙϯενΣοΫ͕αΫͬͱग़དྷΔͱྑ͍
    •៉ྷͳ࢓༷ॻΛ࡞Δͱ໰͍߹Θͤίετ͕ݮΔ
    •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍
    •࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱྑ
    ͍
    •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱྑ͍
    

    View Slide

19. ҙ֎ͱߟྀ఺͕ଟ͍ʜʂ
    

    View Slide

20. 0QFO"1*4QFDJpDBUJPO͕
    ղܾͯ͘͠ΕΔ͜ͱ
    

    View Slide

21. © 2016 KUFU, Inc.
    ͓͞Β͍
    •RESTful API Λهड़͢ΔͨΊͷ࢓༷
    • ͕ Λϕʔεʹࡦఆ
    0QFO"1*4QFDJpDBUJPOͱ͸
    4XBHHFS͸3&45GVM"1*هड़࢓༷ͷ΄͔
    ͍͔ͭ͘ͷπʔϧ܈ʹΑͬͯߏ੒͞Ε͍ͯ·͢
    

    View Slide

22. © 2016 KUFU, Inc.
    جૅ஌ࣝ
    4XBHHFSͷߏ੒
    4XBHHFS$PSF
    8FC"1*ʹ࣮૷ʹଇͨ͠
    4XBHHFS4QFDΛฦ͢Τϯυ
    ϙΠϯτΛੜ΍͢ϥΠϒϥϦ
    4XBHHFS6*
    4XBHHFS4QFDΛ͍͍ײ͡ʹ
    ϨϯμϦϯά͢Δ)5.-
    4XBHHFS4QFD
    4XBHHFSͷ࢓༷ʹ४ͯ͡
    3&45"1*Λهड़ͨ͠
    +40/:.-
    ੜ੒
    ಡΈࠐΈ
    4XBHHFS&EJUPS
    ϒϥ΢β্Ͱ4XBHHFS4QFD
    Λهड़͢Δπʔϧ
    3&45GVM"1*
    $MJFOU4%,
    ੜ੒
    

    View Slide

23. © 2016 KUFU, Inc.
    جૅ஌ࣝ
    4XBHHFSͷߏ੒
    4XBHHFS$PSF
    8FC"1*ʹ࣮૷ʹଇͨ͠
    4XBHHFS4QFDΛฦ͢Τϯυ
    ϙΠϯτΛੜ΍͢ϥΠϒϥϦ
    4XBHHFS6*
    4XBHHFS4QFDΛ͍͍ײ͡ʹ
    ϨϯμϦϯά͢Δ)5.-
    4XBHHFS4QFD
    4XBHHFSͷ࢓༷ʹ४ͯ͡
    3&45"1*Λهड़ͨ͠
    +40/:.-
    ੜ੒
    ಡΈࠐΈ
    4XBHHFS&EJUPS
    ϒϥ΢β্Ͱ4XBHHFS4QFD
    Λهड़͢Δπʔϧ
    3&45GVM"1*
    $MJFOU4%,
    ੜ੒
    4XBHHFSͰ࢓༷ॻΛੜ੒͢Δϑϩʔʹண໨͠·͢
    

    View Slide

24. © 2016 KUFU, Inc.
    Swagger Core + Swagger Spec + Swagger UI
    ಋೖͷεςοϓ
    4UFQ
    4XBHHFS$PSF
    ͷಋೖ
    4UFQ
    4XBHHFS4QFD
    ͷ֬ೝ
    4UFQ
    4XBHHFS6*
    ͷಋೖ
    w ϝδϟʔͳ8"'Ͱ͋
    Ε͹ϥΠϒϥϦ͕͋Γ
    ·͢
    w +BWBͩͱΞϊςʔγϣ
    ϯɺ3VCZͩͱ%4-Ͱ
    "1*Λهड़͍͖ͯ͠·
    ͢
    w 4XBHHFS4QFDΛऔಘ
    ͢ΔΤϯυϙΠϯτ͕
    ੜ͑·͢
    w )551(&5ͯ͠Ϩεϙ
    ϯεΛ֬ೝͯ͠Έ·͠ΐ
    ͏
    w 4XBHHFS6*Λμ΢ϯ
    ϩʔυͯ͠࢓༷ॻΛද
    ࣔͯ͠Έ·͠ΐ͏
    w ϥΠϒϥϦʹΑͬͯ͸
    ࢓༷ॻΛදࣔ͢ΔΤϯ
    υϙΠϯτΛੜ΍͢΋
    ͷ΋͋Γ·͢
    

    View Slide

25. © 2016 KUFU, Inc.
    Swagger UI
    4XBHHFS6*
    

    View Slide

26. © 2016 KUFU, Inc.
    Swagger UI
    •Ξϊςʔγϣϯ΍ DSL Ͱهड़ͨ͠ API ͷઆ໌͕
    ៉ྷʹϨϯμϦϯά͞Ε·͢
    •ϥΠϒϥϦʹΑͬͯ͸ Markdown Ͱॻ͘͜ͱ
    ΋Մೳ
    •τʔΫϯೝূͷػߏ΋උΘ͍ͬͯ·͢
    •ϦΫΤετύϥϝʔλͷઆ໌Λݟͳ͕Βɺ࣮ࡍ
    ʹΫΤϦΛߏஙͯ͠ϨεϙϯεΛ֬ೝͰ͖·͢
    

    View Slide

27. © 2016 KUFU, Inc.
    Swagger UI
    •Swagger UI ͸γϯϓϧͳ HTML5 ͳͷͰɺ
    Ϗϡʔ͸ൺֱత؆୯ʹΧελϚΠζՄೳͰ͢
    •৭ຯͳͲΛௐ੔ͨ͠ςʔϚ΋ެ։͞Ε͍ͯ·͢
    

    View Slide

28. ࠓ·Ͱͷ՝୊͸
    ͲͷΑ͏ʹղܾ͞ΕΔ͔
    

    View Slide

29. © 2016 KUFU, Inc.
    Swagger ͷಋೖʹΑΔ՝୊ղܾ
    ਓ͸࢓༷ॻΛ੔උ͠ͳ͍
    ࣮૷ʹଇ͢ΔͨΊ಺༰͸
    ৗʹ࠷৽ͷঢ়ଶͱͳΔ
    ϒϥ΢β্Ͱ
    ϨεϙϯενΣοΫΛ͍ͨ͠
    4XBHHFS6*্Ͱύϥϝʔλߏஙͱ
    ςετϦΫΤετ͕Մೳ
    ៉ྷͳ࢓༷ॻΛ࡞Δͱ
    ໰͍߹Θͤίετ͕ݮΔ
    σϑΥϧτͰ΋ͦͦ͜͜៉ྷʹͳΔɻ
    ඞཁʹԠͯ͡ΧελϚΠζՄೳ
    ࢓༷ॻͱιʔείʔυ͸
    ͚ۙΕ͹͍ۙ΄Ͳྑ͍
    ιʔείʔυ্ʹهड़͞ΕΔ
    ࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ
    ഑෍Ͱ͖Δͱྑ͍
    ͦͷؾʹͳΕ͹4XBHHFS4QFDΛ
    1%'ͳͲ΁ม׵Մೳ
    ࢓༷Λߏ଄Խ͞ΕͨσʔλͰ
    औಘͰ͖Δͱྑ͍
    4XBHHFS4QFDΛ
    )551ͰऔಘՄೳ
    

    View Slide

30. ͳΜ͔ͩͱͯ΋ྑͦ͞͏ʜ
    

    View Slide

31. 0QFO"1*4QFDJpDBUJPOͷ࣮ફ
    

    View Slide

32. 4NBSU)3"1*
    

    View Slide

33. © 2016 KUFU, Inc.
    SmartHR API
    ػೳ 4NBSU)3ैۀһ৘ใͷݕࡧ
    ࣮૷೥୅ ೥
    ࣮૷ݴޠ 3VCZ
    ར༻
    ϑϨʔϜϫʔΫ
    (SBQF
    Ϩεϙϯεܗࣜ +40/
    *'࢓༷ॻ 4XBHHFS
    جຊεϖοΫ
    

    View Slide

34. © 2016 KUFU, Inc.
    SmartHR API
    •ઌʹ WebAPI Λ࣮૷ͯ͠ɺޙ͔Β Swagger
    Spec Λੜ੒͢ΔΞϓϩʔνΛͱΓ·ͨ͠
    •׬શʹ RESTful ͳઃܭͰɺτʔΫϯೝূ΋͋Γ
    ·͢
    •Swagger UI ͸͔ͳΓΧελϚΠζͯ͋͠Γ·͢
    

    View Slide

35. © 2016 KUFU, Inc.
    SmartHR API
    4XBHHFS$PSF
    

    View Slide

36. © 2016 KUFU, Inc.
    SmartHR API
    4XBHHFS4QFD
    

    View Slide

37. © 2016 KUFU, Inc.
    SmartHR API
    4XBHHFS6*
    

    View Slide

38. ͳ͔ͳ͔ྑ͍࢓্͕Γʂ
    ӡ༻ίετ΋ؾʹͳΒͳ͍
    

    View Slide

39. ·ͱΊ
    

    View Slide

40. © 2016 KUFU, Inc.
    ·ͱΊ
    •OpenAPI Specification Λར༻͢Δͱ௿ίετ
    Ͱ͖ͪΜͱͨ͠࢓༷ॻ͕࡞ΕΔ
    •ϦΫΤετνΣοΫπʔϧͱͯ͠΋࢖͑Δ
    •಺༰͕௠෗Խ͢ΔϦεΫ΋௿͍
    •ར༻͍ͯ͠Δ WAF ʹରԠ͢ΔϥΠϒϥϦ͕͋
    Ε͹ಋೖ΋ൺֱత؆୯
    

    View Slide

41. 0QFO"1*4QFDJpDBUJPOͰ
    εϚʔτʹ"1*Λӡ༻͠·͠ΐ͏ʂ
    

    View Slide

42. ΤϯδχΞืूͯ͠·͢
    ࠙਌ձͰ͓࿩͠·͠ΐ͏ʂCFFST
    w3VCZPO3BJMT
    w#޲͚4BB4
    wݹͯ͘ڊେͳ੍౓Λ)BDL͍ͨ͠
    w4NBSU)3"1*Λӡ༻͍ͨ͠
    

    View Slide