APIドキュメントにまつわる試行錯誤 #gotandajs

2016-09-02 Gotanda.js #5 の発表資料

Transcript

1. APIドキュメントにまつわる 試行錯誤 2016/09/02 Gotanda.JS #5 @mizuki_r
2. @mizuki_r (株)モバイルファクトリー フロントエンドエンジニア JS, Perl Angular, Vue, Riot “HTMLは情報設計言語です！” 2
3. 本日のお題 3
4. APIドキュメントにまつわる 試行錯誤
5. ――を妄想している、 という話をします。
6. 背景
7. 最近の開発スタイル ʘUIϑΝʔετʗ ཁ݅ UI API ϞοΫ API αʔ ό ʔ ·ͣ͸UI ৘ใΛ੔ཧ͠ αʔόΛ ࡞Γ UIʹ൓ө͢Δ
8. 最近の開発スタイル • ϑϩϯτerͰAPIϞοΫΛ࡞Δ • αʔόer͸ϞοΫΛݩʹAPIΛ࡞Δ ʘAPIϞοΫͱ͍͏ίϛϡχέʔγϣϯπʔϧʗ
9. ユーザに対して どういう価値を提供するか？ を土台に作れる！ (๑•̀Ŷ•́๑)✧
10. 悩み
11. モックの例 
    (&5
    BQJVTFSVTFS@OBNF
    
    ݸਓ৘ใΛͱͬͯ͘Δ
    \
    
    
    OBNF
    ʠVTFS@OBNFʡ
    
    
    BHF
    
    ^
    ʘJSON5ʗ
12. よくあること • APIϞοΫͱαʔόͷϨεϙϯε͕ζϨΔ • POSTͷϦΫΤετύϥϝʔλ͕Θ͔Βͳ͍ • Ωʔ͕ԿΛ͍ࣔͯ͠Δͷ͔Θ͔Βͳ͍ • ফ͑ͨ͸ͣͷ࢓༷͕ίϝϯτʹ࢒͍ͬͯΔ ʘυΩϡϝϯςʔγϣϯෆ଍ʂʗ
13. 問題… • ࡞੒ऀʹ࢓༷Λ֬ೝ͢Δ • ίʔυΛಡΉ • ࣏͢… ʘ͜ɺίϛϡχέʔγϣϯπʔϧʂʗ
14. ツールで解決
15. API-Blueprint • MarkdownϕʔεͰυΩϡϝϯτΛهड़Ͱ͖ Δ • ύʔαʔΛఏڙ͠ɺ༷ʑͳ֦ு͕͋Δ
16. API-Blueprint • https://apiblueprint.org/ • MarkdownϕʔεͰυΩϡϝϯτΛهड़Ͱ͖ Δ • ύʔαʔΛఏڙ͠ɺ༷ʑͳ֦ு͕͋Δ
17. API-Blueprint
18. with Tools • aglio - HTMLʹυΩϡϝϯτΛ੔ܗ͢Δ • hariko - ϞοΫαʔόΛ্ཱͪ͛Δ
19. with Tools ཁ݅ UI API Blueprint API αʔ ό ʔ UIΛઃܭ ৘ใΛ੔ཧ αʔόͷߏங UIʹ൓ө API υΩϡϝϯτ API ϞοΫ ࣗಈੜ੒
20. 解決できそう • ࢓༷Λ໌จԽͰ͖Δ • ॻ͍ͨ΋ͷ͕ͦͷ··ಈ࡞͢Δ • ٙ໰͕͋ͬͨΒ௥ه͢Ε͹͍͍ʂ ʘίϛϡχέʔγϣϯπʔϧʂʗ
21. でも…
22. 問題は残る… • αʔόͱϞοΫͷ࣮૷ࠩ෼ • API-Blueprintͷ๲େͳ࢓༷ • ֶशίετɺϝϯςίετ ʘӡ༻͕ΊΜͲͦ͘͞͏ʗ
23. 妄想 • ΋͏Ұ੠ཉ͍͠ • αʔόͱͷ࣮૷ࠩ෼Λิ׬Ͱ͖Δ • ֶशίετʹݟ߹͏ޮ཰Խ͕Ͱ͖Δ
24. あっ (ﾟ∀ﾟ)!
25. API-Blueprintのデータで Controllerくらいなら 作れんじゃね？ (ﾟ∀ﾟ)!!
26. 人類はどこまで 自動化できるのか〜？
27. API-Blueprintから取れるもの • ز͔ͭͷσʔλͷωετߏ଄ • category, resource, action,transaction,httpTransaction,httpRequest,ht tpResponse,etc…
28. Controllerが要求するもの • ϦΫΤετͷ൑அ • Method, URL, Parameters • ॲཧͷ൑அ • Modelͱ͔Serviceͷ໊લۭؒ • Ϩεϙϯεߏ଄ • HttpStatus, Body, Header
29. use Amon2::Lite; use JSON::Types; get '/api/user/:user_name' => sub { my ($c, $args) = @_; my $params = $c->req->parametes; my %args = map { $_ => $params->{$_} or $args->{$_} } qw(user_name); my $entity = $c->factory('User')->get(%args); return $c->render_json(+{ name => string($entity->name), age => number($entity->age), }); }; __PACKAGE__->to_app;
30. 
    (SPVQ
    6TFS
    
    (&5
    BQJVTFS\VTFS@OBNF^
    1BSBNFUFST
    VTFS@OBNF
    TUSJOH
    ʜ
    Ϣʔβͷࣝผࢠ
    3FTQPOTF
    
    BQQMJDBUJPOKTPO
    #PEZ
    OBNF
    TUSJOH
    
    Ϣʔβͷࣝผࢠ
    BHF
    OVNCFS
    
    ೥ྸ
    #PEZ
    \
    OBNF
    ʠNJ[VLJʡ
    BHF
    
    ^
31. ͳΜ͔ɺ
    Πέͦ͏ͳؾ͕͢Δʜ
32. DEMO https://gist.github.com/rymizuki/ab99a288dfafa841983182eddc0408c9
33. まとめ
34. まとめ • API-Blueprint with aglio x hariko x ??? • API-BlueprintΛ༻͍ͨίʔυͷࣗಈੜ੒
35. 所感 • υΩϡϝϯτͱϞοΫͱίʔυ͕࿈ಈ • ཧ࿦্࠷ڧ • ΍Ζ͏ͱࢥ͑͹ߦ͚Δ • Ͱ΋ͦͷ೤ྔʹνʔϜ͸͍ͭͯ͜ΕΔ͔…? • ߟྀ͢Δ͜ͱ͕૊߹ͤരൃͯ͠ࢮʹͦ͏…
36. やるなら 有効そう な無茶をしましょう！
37. ご清聴ありがとうございまし た