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

API Meetup #15

API Meetup #15

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

3dc90859154a16826de8c3df3e4d3bce?s=128

Masato SERIZAWA

July 22, 2016
Tweet

Transcript

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

    "1*.FFUVQ
  2. © 2016 KUFU, Inc.  ࣗݾ঺հ ۔ᖒ խਓ @masato_serizawa •

    גࣜձࣾ KUFU ΤϯδχΞ • ΤϯδχΞͱͯ͠ͷΩϟϦΞͷ΄ͱΜͲΛ WebAPI ͷઃܭɾ ։ൃɾӡ༻ɾൢചΛͯ͠ա͍ͯ͝͠·͢ • ͨ·ʹ Hackathon ʹग़ͨΓ͠·͢ • झຯ͸ Data Visualization Ͱ͢
  3. ຊ೔͓࿩͢Δ͜ͱʰ8FC"1*࢓༷ॻͷӡ༻ʱ

  4. © 2016 KUFU, Inc.  ΞδΣϯμ •๻͕ࠓ·ͰؔΘ͖ͬͯͨ WebAPI ͱͦͷ՝୊ •OpenAPI

    Specification ͕ղܾͯ͘͠ΕΔ͜ͱ •OpenAPI Specification ͷ࣮ફ •·ͱΊ
  5. ๻͕ࠓ·ͰؔΘ͖ͬͯͨ 8FC"1*ͱͦͷ՝୊

  6. © 2016 KUFU, Inc.  WebAPI ͷӡ༻ʢ։ൃҎ֎ʣ •WebAPI ʹ͸ I/F

    ࢓༷ॻ΍ϦΫΤεταϯϓϧ ͕෇͖΋ͷͰ͢ •ઃܭɾ࣮૷ʹൺ΂Δͱܰࢹ͞Ε͕ͪͰ͕͢ɺར ༻ऀͷ UX ʹେ͖͘ӨڹΛ༩͑Δ෦෼Ͱ΋͋Γ ·͢ •ͦΕΒʹ͍ͭͯɺաڈʹܞΘͬͨ WebAPI ͔Β ๻ֶ͕Μͩ՝୊΍ཧ૝૾Λ͓఻͑͠·͢
  7. $BTFᴈ໌ظͷ8FC"1*

  8. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI ػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD

    ࣮૷೥୅ ೥୅ॳ಄ ࣮૷ݴޠ +BWB ར༻ ϑϨʔϜϫʔΫ ಛʹͳ͠ Ϩεϙϯεܗࣜ 9.- *'࢓༷ॻ 8PSE جຊεϖοΫ
  9. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •ϦΫΤεταϯϓϧ͕๛෋ʹ͋ͬͨ •HTML

    Ͱॻ͔Ε͍ͯͯɺϦϯΫΛԡ͢ͱϨεϙ ϯε͕֬ೝͰ͖Δ •ͲͷΑ͏ͳϦΫΤετύϥϝʔλ͕͋ͬͯɺͲ ͷΑ͏ͳϨεϙϯε͕͋Δͷ͔͕֬ೝ͠΍͍͢ •ͪΐͬͱͨ͠ςετπʔϧʹ΋ͳΔ (PPE
  10. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •࢓༷ॻ͕͋·Γӡ༻͞Ε͍ͯͳ͔ͬͨ •ࣾ಺ϑΝΠϧڞ༗αʔόͷͲ͔͜ʹ͋Δ

    Word •هࡌͷൈ͚࿙Ε͕໨ཱͭ •࣮૷Λ֬ೝͨ͠ํ͕ૣ͍… •࢓༷ͷ໰͍߹Θ͕ͤࡴ౸͢Δ 1SPCMFN
  11. © 2016 KUFU, Inc.  Case1: ᴈ໌ظͷ WebAPI •࢓༷ॻ͕͔ͬ͠Γ͍ͯ͠ͳ͍ͱ։ൃίετ͚ͩ Ͱͳ͘ίϛϡχέʔγϣϯίετ΋๲Ε্͕Δ

    •ઃܭࢥ૝ͷෆ౷Ұ΋ى͖΍͍͢ •ʢ࢓૊ΈԽ͠ͳ͍ͱʣਓ͸࢓༷ॻΛ੔උ͠ͳ͍ •WebAPI ͸ϒϥ΢β্ͰαΫͬͱϨεϙϯε νΣοΫͰ͖ΔͱḿΔ ๻ֶ͕Μͩ͜ͱ
  12. $BTFͪΐͬͱϞμϯͳ8FC"1*

  13. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI ػೳ εϙοτݕࡧɺॅॴݕࡧɺFUD

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

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

    ϖ࡞ۀ… •ϨεϙϯεαϯϓϧΛషΓ෇͚Δͷେม… •ΤϯλʔϓϥΠζ޲͚ʹผͰ࢓༷ॻΛ༻ҙ͢Δ Α͏ͳ৔߹͸ɺΠν͔Βॻ͖௚͢ඞཁ͕͋ͬͨ 1SPCMFN
  16. © 2016 KUFU, Inc.  Case2: ͪΐͬͱϞμϯͳ WebAPI •៉ྷͳ࢓༷ॻΛ࡞Δͱت͹ΕΔ •৺ͳ͔͠໰͍߹Θͤ΋༑޷తͳ΋ͷʹͳΔؾ͕

    ͢Δ •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍ •࢓༷ॻ͸৭ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱḿ Δ •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱศརͦ͏ ๻ֶ͕Μͩ͜ͱ
  17. ·ͱΊΔͱʜ

  18. © 2016 KUFU, Inc.  ·ͱΊ •ਓ͸࢓༷ॻΛ੔උ͠ͳ͍ •ϨεϙϯενΣοΫ͕αΫͬͱग़དྷΔͱྑ͍ •៉ྷͳ࢓༷ॻΛ࡞Δͱ໰͍߹Θͤίετ͕ݮΔ •࢓༷ॻͱιʔείʔυ͸͚ۙΕ͹͍ۙ΄Ͳྑ͍

    •࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ഑෍Ͱ͖Δͱྑ ͍ •࢓༷Λߏ଄Խ͞ΕͨσʔλͰऔΕΔͱྑ͍
  19. ҙ֎ͱߟྀ఺͕ଟ͍ʜʂ

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

  21. © 2016 KUFU, Inc.  ͓͞Β͍ •RESTful API Λهड़͢ΔͨΊͷ࢓༷ •

    ͕ Λϕʔεʹࡦఆ 0QFO"1*4QFDJpDBUJPOͱ͸ 4XBHHFS͸3&45GVM"1*هड़࢓༷ͷ΄͔ ͍͔ͭ͘ͷπʔϧ܈ʹΑͬͯߏ੒͞Ε͍ͯ·͢
  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%, ੜ੒
  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Ͱ࢓༷ॻΛੜ੒͢Δϑϩʔʹண໨͠·͢
  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 ϥΠϒϥϦʹΑͬͯ͸ ࢓༷ॻΛදࣔ͢ΔΤϯ υϙΠϯτΛੜ΍͢΋ ͷ΋͋Γ·͢
  25. © 2016 KUFU, Inc.  Swagger UI 4XBHHFS6*

  26. © 2016 KUFU, Inc.  Swagger UI •Ξϊςʔγϣϯ΍ DSL Ͱهड़ͨ͠

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

    HTML5 ͳͷͰɺ Ϗϡʔ͸ൺֱత؆୯ʹΧελϚΠζՄೳͰ͢ •৭ຯͳͲΛௐ੔ͨ͠ςʔϚ΋ެ։͞Ε͍ͯ·͢
  28. ࠓ·Ͱͷ՝୊͸ ͲͷΑ͏ʹղܾ͞ΕΔ͔

  29. © 2016 KUFU, Inc.  Swagger ͷಋೖʹΑΔ՝୊ղܾ ਓ͸࢓༷ॻΛ੔උ͠ͳ͍ ࣮૷ʹଇ͢ΔͨΊ಺༰͸ ৗʹ࠷৽ͷঢ়ଶͱͳΔ

    ϒϥ΢β্Ͱ ϨεϙϯενΣοΫΛ͍ͨ͠ 4XBHHFS6*্Ͱύϥϝʔλߏஙͱ ςετϦΫΤετ͕Մೳ ៉ྷͳ࢓༷ॻΛ࡞Δͱ ໰͍߹Θͤίετ͕ݮΔ σϑΥϧτͰ΋ͦͦ͜͜៉ྷʹͳΔɻ ඞཁʹԠͯ͡ΧελϚΠζՄೳ ࢓༷ॻͱιʔείʔυ͸ ͚ۙΕ͹͍ۙ΄Ͳྑ͍ ιʔείʔυ্ʹهड़͞ΕΔ ࢓༷ॻ͸༷ʑͳϑΥʔϚοτͰ ഑෍Ͱ͖Δͱྑ͍ ͦͷؾʹͳΕ͹4XBHHFS4QFDΛ 1%'ͳͲ΁ม׵Մೳ ࢓༷Λߏ଄Խ͞ΕͨσʔλͰ औಘͰ͖Δͱྑ͍ 4XBHHFS4QFDΛ )551ͰऔಘՄೳ
  30. ͳΜ͔ͩͱͯ΋ྑͦ͞͏ʜ

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

  32. 4NBSU)3"1*

  33. © 2016 KUFU, Inc.  SmartHR API ػೳ 4NBSU)3ैۀһ৘ใͷݕࡧ ࣮૷೥୅

    ೥ ࣮૷ݴޠ 3VCZ ར༻ ϑϨʔϜϫʔΫ (SBQF Ϩεϙϯεܗࣜ +40/ *'࢓༷ॻ 4XBHHFS جຊεϖοΫ
  34. © 2016 KUFU, Inc.  SmartHR API •ઌʹ WebAPI Λ࣮૷ͯ͠ɺޙ͔Β

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

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

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

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

  39. ·ͱΊ

  40. © 2016 KUFU, Inc.  ·ͱΊ •OpenAPI Specification Λར༻͢Δͱ௿ίετ Ͱ͖ͪΜͱͨ͠࢓༷ॻ͕࡞ΕΔ

    •ϦΫΤετνΣοΫπʔϧͱͯ͠΋࢖͑Δ •಺༰͕௠෗Խ͢ΔϦεΫ΋௿͍ •ར༻͍ͯ͠Δ WAF ʹରԠ͢ΔϥΠϒϥϦ͕͋ Ε͹ಋೖ΋ൺֱత؆୯
  41. 0QFO"1*4QFDJpDBUJPOͰ εϚʔτʹ"1*Λӡ༻͠·͠ΐ͏ʂ

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