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

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 ServerBrowser
Response/HTTP HTML
Request/HTTP GET
UI

9. Dynamics 365 Web API(OData)
Application Web Server
Response/JSON,XML
Request/HTTP GETWEB
API

10. Dynamics 365 Web API(OData)
もうちょっと見やすく
Application Web Server
Response/JSON,XML
Request/HTTP GETWEB
API

11. （※補足）なんでWEB APIなんてあるの？
 アプリケーションはビジネスロジックを内包している
 DBを直接触ることはご法度
Application Web Server
Response/JSON,XML
Request/HTTPWEB
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