WEB API勉強会( Dynamics 365 )
@sugimomoto
今日のゴール
・なぜWeb APIが大事なのかがわかる
・OData SOAP RESTの違いがわかる
・Dynamics CRM Web API(OData)の基本がわかる
今日のスライドで出てくる単語
Web API
HTTP
REST
REST full
Open API(Swagger)
SOAP
XML
JSON
TCP/IP
OSI参照モデル
そもそもWeb APIとは何か?
……の前に、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
プログラム(ソフトウェア)同士が連携するための接続窓口一連の処理をまとめたもの
プログラム(ソフトウェア)同士が連携するためのネットワーク(HTTP/S)ベース接続窓口
では、改めてWeb APIとは?
Web API(Web Application Programming Interface)
厳密な定義は無いが、HTTP・HTTPSのプロトコルを用いて、ネットワーク越しに呼び出すアプリケーション間のプログラミング用インターフェースのこと
UI = ブラウザ・デスクトップアプリケーション等で呼び出すのはユーザーインターフェース(UI)
API = プログラムが呼び出すものがプログラミングインターフェース(API)
WEB API = HTTP・HTTPSのプロトコルを用いて、ネットワーク越しに呼び出すプログラミングインターフェース
改めて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
Dynamics 365 UI(User Interface)
User Web ServerBrowser
Response/HTTP HTML
Request/HTTP GETUI
Dynamics 365 Web API(OData)
Application Web Server
Response/JSON,XML
Request/HTTP GETWEB
API
Dynamics 365 Web API(OData)
もうちょっと見やすく
Application Web Server
Response/JSON,XML
Request/HTTP GETWEB
API
(※補足)なんでWEB APIなんてあるの?
アプリケーションはビジネスロジックを内包している
DBを直接触ることはご法度
Application Web Server
Response/JSON,XML
Request/HTTPWEB
API
DB
データベースに直接参照・操作を実行すればいいんじゃないの?
ビジネスロジックを踏まえて入出力を行っている
なぜWeb APIを知らなければいけないか?
Question.今世の中にオープンなWeb APIはいくつ存在しているか?
オープンな Web API だけで17,000種類
引用元:これから始めるエンタープライズ Web API 開発
https://www.ogis-ri.co.jp/otc/hiroba/technical/WebAPI/part1.html
2015年時点で14,000件弱2010年~2015年までで
およそ7倍に!
種類も様々・用途も様々①
引用元:API革命 P.140 業務システムの活用は3タイプ
https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
種類も様々・用途も様々②
引用元:API革命 P.140 業務システムの活用は3タイプ
https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
Web APIを利用する側:開発スタイルの変化
引用元:API革命 P.131SaaS APIで開発スタイルが変わる
https://www.amazon.co.jp/dp/B073PRLBB5/ref=dp-kindle-redirect?_encoding=UTF8&btkr=1
Web APIを提供する側:APIの普遍化
“いまや会社を興す際、「ホームページを作成するか」という議論はナンセンスですが、同じく「APIを作るか、公開するか」という議論は終わっていると言ってもいいでしょう。誤解を恐れずに言うと、「ホームページのない会社は存在しないのと同じ」なのと同様に、「APIがなければサービスがないのと同じ」という段階に差しかかっています。”
引用:「API経済」の転換期、日本は生き残れるか~これだけは押さえておきたい3つの戦略【特集:New Order】
http://type.jp/et/log/article/webapi-neworder
もうちょっとWEB APIの世界を知る
最近あったWeb APIに関する質問
RESTとSOAPって何が違うの?
RESTってプロトコルなんでしょ?
ODataって何?
“REST・SOAPの違い“を結論から
REST = ソフトウェアアーキテクチャスタイルのひとつ
SOAP = XML Webサービスのための、XMLベースのRPCプロトコル
比較するべきレイヤーではない
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っぽい何か
改めて“REST”とは?
REST = Representational State Transfer
>Representational State Transfer (REST) は、ウェブのような分散ハイパーメディアシステムのためのソフトウェアアーキテクチャのスタイルのひとつである。
引用元:Wikipedia REST
https://ja.wikipedia.org/wiki/REST
RESTとは? もう一度
ソフトウェアアーキテクチャの
スタイルのひとつ
つまり、Not Protocol
Web APIをRESTたらしめる“原則“(≠規約)
Stateless:ステートレスなクライアント/サーバプロトコル
Uniform Interface:すべての情報(リソース)に適用できるHTTPメソッドの定義
Addressability:リソースを一意に識別する「汎用的な構文(URL)」の定義
Connectability:アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディア(リソースリンク)の使用」
上記の原則に従っているアーキテクチャをREST Fulと言う
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”}
特に無いかな?
じゃあSOAPって何?
SOAP(ソープ)は、XML-RPCから発展した、XML Webサービスのための、XML
ベースのRPCプロトコルである。
RPC(Remote procedure call:リモートプロシージャコール)
とっつきづらいけど、誤解を恐れず言えばネットワーク上からアクセスすることができる”関数”
とってもシンプルなSOAPの例
引用元:@IT WSDL:Webサービスのインターフェイス情報
http://www.atmarkit.co.jp/ait/articles/0303/18/news003.html
HTTP/1.1 200 OKContent-Type: text/xml; charset=utf-8Date: Wed, 12 Mar 2003 15:06:08 GMTServer: Apache Coyote/1.0Connection: close
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelopexmlns: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:getPriceResponsesoapenv: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.0Content-Type: text/xml; charset=utf-8Accept: application/soap+xml, application/dime, multipart/related, text/*User-Agent: Axis/1.1betaHost: localhostCache-Control: no-cachePragma: no-cacheSOAPAction: ""Content-Length: nnnn
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelopexmlns: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:getPricesoapenv: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サービスの例
抑えておきたいWSDL
(Web Services Description Language)
引用元:@IT WSDL:Webサービスのインターフェイス情報
http://www.atmarkit.co.jp/ait/articles/0303/18/news003.html
SOAPにしたがって記述されたWeb APIの仕様を記述した文書
関数の仕様と言ってもいいかもしれない
じゃあ、ODataは?
ODataは、データモデルの記述、およびそれらのモデルに従ったデータの編集および照会をサポートするプロトコル。
・メタデータ:特定のデータプロバイダによって公開されるデータモデルの機械可読の記述。
・データ:データエンティティのセットとそれらの間の関係。
・クエリー:サービスがフィルタリングとデータへの変換を実行するよう要求し、結果を返す。
・編集:データの作成、更新、および削除。
・操作:カスタムロジックの呼び出し
・ボキャブラリ:カスタムセマンティクスの付加
引用元:OData Web Services
http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html
表形式データの“編集”および“照会”をサポートしたREST Fulなプロトコル
Query Support URL Components
表形式のデータを参照するための各種Queryをサポート
各種データのクエリ・フィルターをサポート
データの編集も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な形式でデータの操作をサポートわかりやすい
じゃあ、GraphQLは?
GraphQLはAPI用のクエリ言語であり、データ用に定義した型システムを使用してクエリを実行するためのサーバー側のランタイムです。
GraphQL自体は2012年からFacebookで開発。2015年7月にRFCドラフト案を公開。
Schema(APIの定義)の存在と問合わせ言語仕様がセット
見たほうが早い。GraphQL Query Sample
{"user": {"name": "User One","friends": [{"name": "Friend One"
},{"name": "Friend Two"
}]}
}
user(id: "1") {namefriends {name
}}
Request Response
type User {name: Stringage: Intfriends: [User]
}
type Query {me: Useruser(id: Int): User
}
Query Scheme User Scheme
引用元:GraphQLについて調べてみた サイバーエージェント公式エンジニアブログ
https://ameblo.jp/principia-ca/entry-12060337336.html
最後、OpenAPIとは?
OpenAPI Specification(OAS)は、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピュータの両方がサービスの機能を発見して理解することを可能にする、プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を定義します。
引用元:https://github.com/OAI/OpenAPI-Specification
REST APIを記述・設計・定義するための仕様極端に言えば、「REST版WSDL」
OpenAPI(Swagger)を構成する要素
Tool Description
Swagger SpecREST APIに対して Swaggerの仕様に準じたドキュメント
Swagger CoreREST APIの実装からSwagger specを生成するためのライブラリ
Swagger Codegenコマンドラインツール Swagger JSONからクライアントコード生成
Swagger UISWagger 準拠 API (Swagger SPec)から動的にドキュメントを生成するツール
Swagger Editorブラウザ上で動くJSON/YAMLのエディタリアルタイムで構文チェック
引用元:Swaggerとは何か?プログラマでありたい
http://blog.takuros.net/entry/2015/12/02/082248
今後Web APIは標準化されていくか?→わかんない。・プロトコル化は難しいかも・記述様式のデファクトスタンダードはOpenAPIかも
個人的にはODataがもっと広まってほしい。SOAPはオワコンっぽい。GraphQLは様子見。あまり伸びない感。
ようやくDynamics 365 Web APIについて
Dynamics CRM WEB APIは3種類
REST API(OData)
SOAP APIWeb 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を知ることと同義と言っても過言じゃない
Query Support URL Components
表形式のデータを参照するための各種Queryをサポート
再掲
各種データのクエリ・フィルターをサポート
再掲
データの編集も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な形式でデータの操作をサポートわかりやすい
再掲
参考文献
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/
参考文献
何故これからの時代にAPIが重要なのか?
https://www.slideshare.net/pinahirano/api-78108172
Swaggerとは何か? - プログラマでありたい
http://blog.takuros.net/entry/2015/12/02/082248