Web API（Dynamics 365 ）勉強会

会社の新人向けにWeb APIの勉強会を実施した時の資料です。
最終的にDynamics 365の話をするんですが、ほとんどWeb APIとはなんぞや？　みたいな資料です。
色々と引用させてもらっています。

Transcript

1. WEB API勉強会 （ Dynamics 365 ） @sugimomoto
2. 今日のゴール ・なぜWeb APIが大事なのかがわかる ・OData SOAP RESTの違いがわかる ・Dynamics CRM Web API(OData)の基本がわかる
3. 今日のスライドで出てくる単語  Web API  HTTP  REST  REST full  Open API(Swagger)  SOAP  XML  JSON  TCP/IP  OSI参照モデル
4. そもそもWeb APIとは何か？
5. ……の前に、APIってなんだっけ？ ❝ アプリケーションプログラミングインタフェース（API、英: Application Programming Interface）とは、ソフトウェアコンポーネントが互いにやりとりす るのに使用するインタフェースの仕様である。 APIには様々な形態があり、POSIXのような国際規格、マイクロソフトのWindows APIのようなベンダーによる文書、プログラミング言語のライブラリ（例えば、 C++のStandard Template LibraryやJava API（英語版）など）がある。❞ 引用元：Wikipedia API https://ja.wikipedia.org/wiki/%E3%82%A2%E3%83%97%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E 3%83%97%E3%83%AD%E3%82%B0%E3%83%A9%E3%83%9F%E3%83%B3%E3%82%B0%E3%82%A4%E3%83%B3%E3%82%BF%E3%83%95%E 3%82%A7%E3%83%BC%E3%82%B9 プログラム（ソフトウェア）同士が連携するための接続窓口 一連の処理をまとめたもの
6. プログラム（ソフトウェア）同士が連携するための ネットワーク（HTTP/S）ベース接続窓口 では、改めてWeb APIとは？ Web API（Web Application Programming Interface） 厳密な定義は無いが、HTTP・HTTPSのプロトコルを用いて、ネットワーク越しに呼び出す アプリケーション間のプログラミング用インターフェースのこと UI ＝ ブラウザ・デスクトップアプリケーション等で呼び出すのはユーザーインターフェース（UI） API ＝ プログラムが呼び出すものがプログラミングインターフェース（API） WEB API = HTTP・HTTPSのプロトコルを用いて、ネットワーク越しに呼び出すプログラミング インターフェース
7. 改めてWeb APIとは？ User Application Application Application Web Server Web Server Browser Request/Non Format Response/Non Format Response/HTTP HTML Request/HTTP GET Response/JSON,XML Request/HTTP GET API UI WEB API
8. Dynamics 365 UI(User Interface) User Web Server Browser Response/HTTP HTML Request/HTTP GET UI
9. Dynamics 365 Web API(OData) Application Web Server Response/JSON,XML Request/HTTP GET WEB API
10. Dynamics 365 Web API(OData) もうちょっと見やすく Application Web Server Response/JSON,XML Request/HTTP GET WEB API
11. （※補足）なんでWEB APIなんてあるの？  アプリケーションはビジネスロジックを内包している  DBを直接触ることはご法度 Application Web Server Response/JSON,XML Request/HTTP WEB API DB データベースに直接参照・操作を 実行すればいいんじゃないの？ ビジネスロジックを踏まえて 入出力を行っている
12. なぜWeb APIを知らなければいけないか？
13. Question. 今世の中にオープンなWeb APIは いくつ存在しているか？
14. オープンな Web API だけで17,000種類 引用元：これから始めるエンタープライズ Web API 開発 https://www.ogis-ri.co.jp/otc/hiroba/technical/WebAPI/part1.html 2015年時点で14,000件弱 2010年～2015年までで およそ7倍に！
15. 種類も様々・用途も様々① 引用元：API革命 P.140 業務システムの活用は3タイプ https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
16. 種類も様々・用途も様々② 引用元：API革命 P.140 業務システムの活用は3タイプ https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
17. Web APIを利用する側：開発スタイルの変化 引用元：API革命 P.131SaaS APIで開発スタイルが変わる https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
18. Web APIを提供する側：APIの普遍化 “いまや会社を興す際、「ホームページを作成するか」という議論はナンセンスで すが、同じく「APIを作るか、公開するか」という議論は終わっていると言っても いいでしょう。誤解を恐れずに言うと、「ホームページのない会社は存在しない のと同じ」なのと同様に、「APIがなければサービスがないのと同じ」という段階 に差しかかっています。” 引用：「API経済」の転換期、日本は生き残れるか～これだけは押さえておきたい 3つの戦略【特集:New Order】 http://type.jp/et/log/article/webapi-neworder
19. もうちょっとWEB APIの世界を知る
20. 最近あったWeb APIに関する質問 RESTとSOAPって何が違うの？ RESTってプロトコルなんでしょ？ ODataって何？
21. “REST・SOAPの違い“を結論から  REST ＝ ソフトウェアアーキテクチャスタイルのひとつ  SOAP ＝ XML Webサービスのための、XMLベースのRPCプロトコル 比較するべきレイヤーではない
22. Open API REST “私の”Web API界隈における全体イメージ HTTP/S OData (OASIS) SOAP (RFC 4227) RPC Graph QL (RFC DRAFT) UDP/TCP Application Layer Transport Layer Other Layer REST っぽい何か
23. 改めて“REST”とは？  REST = Representational State Transfer ＞Representational State Transfer (REST) は、ウェブのような分散ハイパーメディ アシステムのためのソフトウェアアーキテクチャのスタイルのひとつである。 引用元：Wikipedia REST https://ja.wikipedia.org/wiki/REST
24. RESTとは？ もう一度 ソフトウェアアーキテクチャの スタイルのひとつ つまり、Not Protocol
25. Web APIをRESTたらしめる“原則“（≠規約）  Stateless：ステートレスなクライアント/サーバプロトコル  Uniform Interface：すべての情報（リソース）に適用できるHTTPメソッドの定義  Addressability：リソースを一意に識別する「汎用的な構文（URL）」の定義  Connectability：アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディ ア（リソースリンク）の使用」 上記の原則に従っているアーキテクチャを REST Fulと言う
26. Good/Bad REST パターン（極端な例だけど） Stateless Uniform Interface Addressability Connectability Good Pattern 1回目：GET /members Response {name: “kazuya”} 2回目：GET /members Response {name: “kazuya”} /members /members/1234 “リソースの取得” GET /members “リソースの作成” POST /members {name:”kazuya”} 1回目：GET /members Response { name: “kazuya”, href:”https://..../....” } Bad Pattern 1回目：GET /members Response {name: “kazuya1”} 2回目：GET /members Response {name: “kazuya2”} /getMember /postMember (URLに動詞を使わない) “リソースの取得” POST /members “リソースの作成” GET /members {name:”kazuya”} 特に無いかな？
27. じゃあSOAPって何？  SOAP（ソープ）は、XML-RPCから発展した、XML Webサービスのための、XML ベースのRPCプロトコルである。 RPC（Remote procedure call：リモートプロシージャコール） とっつきづらいけど、誤解を恐れず言えば ネットワーク上からアクセスすることができる”関数”
28. とってもシンプルなSOAPの例 引用元：@IT WSDL：Webサービスのインターフェイス情報 http://www.atmarkit.co.jp/ait/articles/0303/18/news003.html HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Date: Wed, 12 Mar 2003 15:06:08 GMT Server: Apache Coyote/1.0 Connection: close <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:getPriceResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://unitec-denki.utj.co.jp/schema/2003/"> <getPriceReturn xsi:type="xsd:int">1575</getPriceReturn> </ns1:getPriceResponse> </soapenv:Body> </soapenv:Envelope> POST /axis/services/Estimate HTTP/1.0 Content-Type: text/xml; charset=utf-8 Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: Axis/1.1beta Host: localhost Cache-Control: no-cache Pragma: no-cache SOAPAction: "" Content-Length: nnnn <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:getPrice soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://unitec-denki.utj.co.jp/schema/2003/"> <Code xsi:type="xsd:string">code-001</Code> <Value xsi:type="xsd:int">30</Value> </ns1:getPrice> </soapenv:Body> </soapenv:Envelope> 文字列型の商品コード（Code）と整数型の商品の個数（Value）を渡すと価格を返すメソッドをWebサービスの例
29. 抑えておきたいWSDL (Web Services Description Language) 引用元：@IT WSDL：Webサービスのインターフェイス情報 http://www.atmarkit.co.jp/ait/articles/0303/18/news003.html SOAPにしたがって記述されたWeb APIの 仕様を記述した文書 関数の仕様と言ってもいいかもしれない
30. じゃあ、ODataは？ ODataは、データモデルの記述、およびそれらのモデルに従ったデータの編集および照会をサポートす るプロトコル。 ・ メタデータ：特定のデータプロバイダによって公開されるデータモデルの機械可読の記述。 ・ データ：データエンティティのセットとそれらの間の関係。 ・ クエリー：サービスがフィルタリングとデータへの変換を実行するよう要求し、結果を返す。 ・ 編集：データの作成、更新、および削除。 ・ 操作：カスタムロジックの呼び出し ・ボキャブラリ：カスタムセマンティクスの付加 引用元：OData Web Services http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html 表形式データの“編集”および“照会”をサポートした REST Fulなプロトコル
31. Query Support URL Components 表形式のデータを参照するための各種Queryをサポート
32. 各種データのクエリ・フィルターをサポート
33. データの編集もREST Fulな形式でサポート 新規作成 更新 削除 POST http://serviceurl/People HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 Content-Type: application/json { 'UserName’:’Sugimomoto', 'FirstName’:’Kauzya', 'LastName’:’Sugimoto', } PUT http://serviceurl/People(1) HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 Content-Type: application/json { 'UserName’:’UpdateName', } DELETE http://serviceurl/People(1) HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 REST Fulな形式でデータの操作をサポート わかりやすい
34. じゃあ、GraphQLは？ GraphQLはAPI用のクエリ言語であり、データ用に定義した型システムを使用して クエリを実行するためのサーバー側のランタイムです。 GraphQL自体は2012年からFacebookで開発。2015年7月にRFCドラフト案を公開。 Schema（APIの定義）の存在と問合わせ言語仕様がセット
35. 見たほうが早い。GraphQL Query Sample { "user": { "name": "User One", "friends": [ { "name": "Friend One" }, { "name": "Friend Two" }] } } user(id: "1") { name friends { name } } Request Response type User { name: String age: Int friends: [User] } type Query { me: User user(id: Int): User } Query Scheme User Scheme 引用元：GraphQLについて調べてみた サイバーエージェント公式エンジニアブログ https://ameblo.jp/principia-ca/entry-12060337336.html
36. 最後、OpenAPIとは？  OpenAPI Specification（OAS）は、ソースコードへのアクセス、追加ドキュメ ント、またはネットワークトラフィックの検査を必要とせずに、人間とコン ピュータの両方がサービスの機能を発見して理解することを可能にする、 プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を 定義します。 引用元：https://github.com/OAI/OpenAPI-Specification REST APIを記述・設計・定義するための仕様 極端に言えば、「REST版WSDL」
37. OpenAPI(Swagger)を構成する要素 Tool Description Swagger Spec REST APIに対して Swaggerの仕様に準じたドキュ メント Swagger Core REST APIの実装からSwagger specを生成するため のライブラリ Swagger Codegen コマンドラインツール Swagger JSONからクライ アントコード生成 Swagger UI SWagger 準拠 API （Swagger SPec）から動的にド キュメントを生成するツール Swagger Editor ブラウザ上で動くJSON/YAMLのエディタリアルタ イムで構文チェック 引用元：Swaggerとは何か？ プログラマでありたい http://blog.takuros.net/entry/2015/12/02/082248
38. 今後Web APIは標準化されていくか？ →わかんない。 ・プロトコル化は難しいかも ・記述様式のデファクトスタンダードはOpenAPIかも 個人的にはODataがもっと広まってほしい。 SOAPはオワコンっぽい。 GraphQLは様子見。あまり伸びない感。
39. ようやくDynamics 365 Web APIについて
40. Dynamics CRM WEB APIは3種類 REST API （OData） SOAP API Web API （REST/OData） [Your Organization Root URL] /xrmservices/2011/organizationdata.svc [Your Organization Root URL] /XRMServices/2011/Organization.svc [Your Organization Root URL] /api/data/v8.2/ もう使わない けど、オンプレだとFormScriptで 使ってるところ多いよね 将来的に廃止予定 でもオンプレ系は現役ばりばり SDKを使って使用することがメイン これからはこれを使ってね Dynamics CRM Web APIで 覚えるべきことは、ODataを知ることと同義と言っても過言じゃない
41. Query Support URL Components 表形式のデータを参照するための各種Queryをサポート 再掲
42. 各種データのクエリ・フィルターをサポート 再掲
43. データの編集もREST Fulな形式でサポート 新規作成 更新 削除 POST http://serviceurl/People HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 Content-Type: application/json { 'UserName’:’Sugimomoto', 'FirstName’:’Kauzya', 'LastName’:’Sugimoto', } PUT http://serviceurl/People(1) HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 Content-Type: application/json { 'UserName’:’UpdateName', } DELETE http://serviceurl/People(1) HTTP/1.1 OData-Version: 4.0 OData-MaxVersion: 4.0 REST Fulな形式でデータの操作をサポート わかりやすい 再掲
44. 参考文献  Webを支える技術 著：山本 陽平  Windowsはなぜ動くのか 著：天野 司  Web API: The Good Parts O’REILLY Japan 著：水野 貴明  API革命 日経MOOK  Web APIとは何なの http://qiita.com/NagaokaKenichi/items/df4c8455ab527aeacf02  WebAPIのこれまでとこれから https://www.slideshare.net/yohei/webapi-36871915  これから始めるエンタープライズ Web API 開発 https://www.ogis-ri.co.jp/otc/hiroba/technical/WebAPI/
45. 参考文献  何故これからの時代にAPIが重要なのか？ https://www.slideshare.net/pinahirano/api-78108172  Swaggerとは何か？ - プログラマでありたい http://blog.takuros.net/entry/2015/12/02/082248