Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Meetup #15

API Meetup #15

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

Masato SERIZAWA

July 22, 2016
Tweet

More Decks by Masato SERIZAWA

Other Decks in Technology

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