Web API（Dynamics 365 ）勉強会

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)

もうちょっと見やすく


Response/JSON,XML

Request/HTTP GETWEB

API

（※補足）なんでWEB APIなんてあるの？

アプリケーションはビジネスロジックを内包している

DBを直接触ることはご法度


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タイプ


Web APIを利用する側：開発スタイルの変化

引用元：API革命 P.131SaaS APIで開発スタイルが変わる


Web APIを提供する側：APIの普遍化

“いまや会社を興す際、「ホームページを作成するか」という議論はナンセンスですが、同じく「APIを作るか、公開するか」という議論は終わっていると言ってもいいでしょう。誤解を恐れずに言うと、「ホームページのない会社は存在しないのと同じ」なのと同様に、「APIがなければサービスがないのと同じ」という段階に差しかかっています。”

引用：「API経済」の転換期、日本は生き残れるか～これだけは押さえておきたい3つの戦略【特集:New Order】

http://type.jp/et/log/article/webapi-neworder

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”}


Response {name: “kazuya”}

/members

/members/1234

“リソースの取得”

GET

/members

“リソースの作成”

POST

/members

{name:”kazuya”}


Response {

name: “kazuya”,

href:”https://..../....”

}

Bad

Pattern


Response {name: “kazuya1”}


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



{

'UserName’:’UpdateName',

}

DELETE http://serviceurl/People(1) HTTP/1.1

OData-Version: 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


/XRMServices/2011/Organization.svc


/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



{

'UserName’:’Sugimomoto',

'FirstName’:’Kauzya',

'LastName’:’Sugimoto',

}

PUT http://serviceurl/People(1) HTTP/1.1

OData-Version: 4.0



{

'UserName’:’UpdateName',

}

DELETE http://serviceurl/People(1) HTTP/1.1

OData-Version: 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

Technology

Web API（Dynamics 365 ）勉強会