Web API仕様 #4447

kiy0taka · 2020-01-22T07:03:55Z

概要(Overview)

外部サービスと連携するためWeb API機能検討する。
プラグインではなく、本体の機能として組み込みたい。

API仕様

GraphQL によるWeb APIを提供する。
GraphQLの仕様に従ってQueryとMutationについて考える。

Query

データを取得するためのQueryとしては、管理画面にある以下の一覧を提供する。

商品一覧
受注一覧
会員一覧

それぞれの一覧はクライアントのクエリに対して、Entityの関連に基づいたデータを返す。

例えば、商品一覧において、商品ID/ステータス/商品規格のコード/販売価格を要求するには以下のようなクエリを実行する。

{
  products {
    id
    name
    ProductClasses {
      id
      code
      price02
      stock
    }
    Status {
      id
      name
    }
  }
}

この場合、EC-CUBEは以下のようなレスポンスを返す。

{
  "data": {
    "products": [
      {
        "id": "1",
        "name": "彩のジェラートCUBE",
        "ProductClasses": [
          {
            "id": "1",
            "code": "cube-01",
            "price02": 110000,
            "stock": null
          },
          {
            "id": "2",
            "code": "cube-01",
            "price02": 110000,
            "stock": null
          }
        ],
        "Status": {
          "id": "1",
          "name": "公開"
        }
      },
      {
        "id": "2",
        "name": "チェリーアイスサンド",
        "ProductClasses": [
          {
            "id": "11",
            "code": "sand-01",
            "price02": 2800,
            "stock": 100
          }
        ],
        "Status": {
          "id": "1",
          "name": "公開"
        }
      }
    ]
  }
}

プラグインなどによるカスタマイズでQueryを追加できる仕組みも提供する。

Mutation

データの変更を行うMutationについては、ビジネスロジックに基づいたユースケースを決定し提供する。
ユースケースについては要検討。

プラグインなどによるカスタマイズでMutationを追加できる仕組みも提供する。

認可

Web APIの認可方法として OAuth 2.0 を提供する。

Webhooks

EC-CUBEのデータ変更をリアルタイムに他システムへ通知するための仕組みとしてWebhookを提供する。
GraphQLで提供するQueryに合わせて以下の情報が変更された場合に通知する。

商品情報
受注情報
会員情報

The text was updated successfully, but these errors were encountered:

kiy0taka · 2020-01-22T07:07:08Z

商品/受注/会員のQueryを実装してみました。
https://github.com/kiy0taka/ec-cube/tree/experimental/graphql

okazy · 2020-01-23T00:40:40Z

3系Issueはこちら
#1530

nanasess · 2020-01-23T02:35:08Z

Web APIの認証方法として OAuth 2.0 を提供する。

細かいところですが、 OAuth2.0 では認可のためのフレームワークですので、認証であれば Open ID Connect になると思います。

okazy · 2020-01-29T08:45:33Z

更新できていないので折りたたみます。

進捗

ニュース

主要な機能の正常系の実装が完了
https://github.com/okazy/ec-cube/tree/experimental/oauth2

基本的な設計指針

kiy0takaさんによるGraph QLの実装と3系の認証機構の設計に準ずる
- https://github.com/kiy0taka/ec-cube/tree/experimental/graphql
- https://github.com/EC-CUBE/eccube-api
本体の拡張機構を利用してqueryとmutationを追加できる仕組みを作る
認証はoauth2-bundleを利用（検討中）
- https://oauth2.thephpleague.com/
- Symfony 4.2 or Symfony 3.4
- https://github.com/thephpleague/oauth2-server

マイルストーン

2月末ベータ版
- 取得
- 認証
春正式リリース(4.0.x)
- 更新
- Webhooks

ベータ版までの進捗

ベータ版の想定形式

branchを作って開発を行う
GitHub内でtagを打ってリリースする

正式リリースの想定形式

ベータ版リリース後の反応を見て変更になる可能性あり

本体のマスターbranchに取り込む
GitHub内でtagを打ってリリースする
パッケージングしてリリース(4.0.4?)

TODO

indexの設定
Entity拡張への対応
oauth2-bundleの要件でPHP7.2以上となる（EC-CUBE4は7.1.3以上）
oauth2-bundleとEC-CUBEのルールの吸収
実装をServiceにまとめて拡張性をあげる
webhooksのプラグインでの登録機構
/authorizeのアクセス制限

tao-s · 2020-02-06T05:53:52Z

src/Eccube/GraphQLじゃなくて、API周りはServiceにまとめた方が良く無いですか？
ApiController->GraphQLApiService->xxxService な感じで

ApiServiceにはApiInterfaceとか作って、RESTとかでも同じの使う感じにして

okazy · 2020-02-07T00:58:37Z

そうですね、特に認証周りは汎用性あると思うので、プラグインなどでも利用できるような機構にしたいと思っています。

pineray · 2020-02-09T20:54:20Z

webhook をプラグインから登録できるようになると楽しいです。
レポジトリを直接さわるのではなく、サービスとか設定ファイル経由で。

okazy · 2020-02-19T06:08:47Z

API開発用のブランチを切りました。
ブランチ名: experimental/api
https://github.com/EC-CUBE/ec-cube/tree/experimental/api

okazy · 2020-02-19T06:36:18Z

experimental/apiブランチにGraphQLとOAuth2.0の実装のプルリクを出しました。
#4474
ぜひご意見や感想などをください。

okazy · 2020-04-09T05:02:04Z

API開発状況まとめ

以下は暫定のものとなり、随時更新をしていきます。

リリーススケジュール

更新系の実装: 6月下旬
外部仕様凍結: 未定
リリース: 未定

2020/5/28 更新

APIの仕様

4.0.x系のプラグインとしてリリース
OAuth2.0
- Grant Type: Authorization Code
- Scope: read,write
GraphQL
- Query
  - Web API仕様 #4447 (comment)
  - 取得できるデータ: 商品一覧、受注一覧、会員一覧
  - それぞれの一覧画面で指定できる検索条件で絞ることが可能
  - [残課題] 日付の取得、ページング、出荷時間による検索
- Mutation
  - 商品規格情報の在庫数を更新
  - 注文出荷情報のステータスを更新

GraphQL Mutationの仕様(案)

商品規格情報の在庫数を更新

パラメータ

Name	type	Description
id	ID	商品規格ID (必須)
stock	Int	商品規格の在庫数 (在庫無制限が無効の場合は必須)
stock_unlimited	Boolean	商品規格の在庫無制限 (必須)

実行例

# 在庫無制限ではない商品
mutation {
    editProductStock (
        id: 1
        stock: 5
        stock_unlimited: false
    ) {
        id
        stock
        stock_unlimited
    }
}

# 在庫無制限の商品
mutation {
    editProductStock (
        id: 1
        stock_unlimited: true
    ) {
        id
        stock
        stock_unlimited
    }
}

注文出荷情報のステータスを更新

パラメータ

Name	type	Description
id	ID	出荷ID (必須)
shipping_delivery_name	String	配送方法 (変更する場合は必須)
shipping_date	String	出荷日 (変更する場合は必須)
tracking_number	String	お問い合わせ番号 (変更する場合は必須)
note	String	出荷用メモ欄 (変更する場合は必須)

※注文情報に紐づく全ての出荷情報に出荷日が入れば、その注文情報が出荷済みとなる。

実行例

mutation {
    editShippingStatus (
        id: 1
        shipping_delivery_name: "サンプル宅配"
        shipping_date: "2020-01-01"
        tracking_number: "tracking0123"
        note: "出荷しました。"
    ) {
        id
        shipping_delivery_name
        shipping_date
        tracking_number
        note
    }
}

懸念

特にプラグイン化するにあたって4.0.3では対応できない部分が出てこないか

変更履歴

20200410: GraphQLのMutationの仕様を見直し
20200413: GraphQL Mutationの仕様(案)を追加

okazy · 2020-04-20T04:11:58Z

現在いただいているフィードバックを一旦洗い出しました。

EC-CUBE4 Web API β フィードバック

必須の改修、実装
- ページング機能
- 日付の取得
- 受注ステータス（伝票番号、出荷日、配送会社の更新）の更新
要望
- 時間単位での取得条件指定（現状日付単位で指定可能、件数的に回避可能だけど本当は欲しい）
- ProductCodeをキーとして在庫数、価格の取得・更新（ProductClassIdで問題ないか確認中）
- CreateDateを範囲指定してOrderを取得（OrderDateでも問題ないか確認中）
- Order.OrderItemsで商品のみ取得（連携側で対応可能だがおそらくあった方が良い）
- フロントエンドでの利用（当初スコープ外だった要件）
  - Authorization Code Grant以外のGrantのサポートの検討
  - Scopeの細分化の検討
  - 購入のAPI
調査が必要な観点
- PHPの要件が7.2以上となることへの対応方針
- 自動テストの作成
- セキュリティ面での強化
  - 鍵を公開ディレクトリ以下に配置することの是非と対策
  - 全会員データ取得可能となることの是非と対策
  - エンドポイントのアクセス制限
  - OpenID Connectの基準に従った認証機能の要否と対策
  - Authorization Code Interception Attack
  - IdP Mix-Up Attack
- プラグインでの実装の検証
  - 必要な拡張機構がすべてそろっているか（環境変数やyamlなど）
  - エンドポイントのURLの調整
- 配送会社の更新
  - 配送業者は文字列で受注に保存されてる。変更しても管理画面での受注編集で戻ってしまう。

nanasess · 2020-04-20T06:23:29Z

ProductCodeをキーとして在庫数、価格の取得・更新（ProductClassIdで問題ないか確認中）

基幹連携などで在庫などの商品情報を更新する場合は、基幹側にマスタ連携する必要が生じるため、ProductClassId だと使えないです。
商品コード(SKU)がベター

nanasess · 2020-04-22T00:49:42Z

鍵を公開ディレクトリ以下に配置することの是非と対策

鍵はデータベースに入れた方が無難かなと

okazy · 2020-05-29T08:23:56Z

APIプラグイン化に向けた課題

PHP7.2以上 (oauth2-bundleの要件)
プラグインでのbundleインストールの検証
yamlファイルの追加および変更の検証
プラグインでの環境変数の設定の検証

atsuyuki-inui · 2020-06-09T07:28:16Z

現状EC-CUBEを利用したwebサイトを運営しており、アプリ化を検討しております。
およそで結構ですのでAPI開発の今後のスケジュールの目処を教えていただけませんか？

okazy · 2020-06-11T02:32:07Z

@atsuyuki-inui
リリーススケジュールは決まっていないのですが、リリースは8月以降になるかと思います。
エンドユーザ向けのアプリ化を検討されておられるのかと思いますが、開発中のAPIは「外部サービスと連携するためWeb API」となります。
リリースされましてもそのままでは利用できないかと思いますのでご注意ください。

atsuyuki-inui · 2020-06-11T02:43:10Z

@okazy ご回答頂きありがとうございます。エンドユーザ向けのアプリとなります。アプリからGraphQL API（Query、Mutation）を叩いてEC-CUBEの機能を使う想定でいました。仕様が固まるのはいつ頃になりますでしょうか？

okazy · 2020-07-01T06:07:37Z

@atsuyuki-inui
EC-CUBE 4.1 のロードマップが公開されました。

#4603

API関連を抜粋すると以下かと思います。

~9月: API開発
~12月: 4.0.5開発

APIの開発は~9月ですが、プラグインでの提供となり、4.0.5以降でないと使えない可能性があります。

okazy · 2020-07-01T06:08:35Z

APIのプラグイン化に向けたリポジトリが作成されました。
https://github.com/EC-CUBE/eccube-api4

okazy mentioned this issue Jan 23, 2020

Web APIの開発 #1530

Closed

okazy added affected:外部仕様外部仕様の変更や追加 enhancement 機能追加 Status: discussion labels Jan 23, 2020

okazy added this to the 4.0.x milestone Jan 23, 2020

okazy mentioned this issue Feb 19, 2020

API: GraphQLとOAuth2.0の実装 #4474

Merged

17 tasks

okazy mentioned this issue Mar 17, 2020

[API] GraphQLでDateTimeを取得するとエラーとなる #4488

Closed

ryo-endo pinned this issue May 11, 2020

chihiro-adachi unpinned this issue Jun 30, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Web API仕様 #4447

Web API仕様 #4447

kiy0taka commented Jan 22, 2020 •

edited by okazy

Loading

kiy0taka commented Jan 22, 2020 •

edited

Loading

okazy commented Jan 23, 2020

nanasess commented Jan 23, 2020

okazy commented Jan 29, 2020 •

edited

Loading

ニュース

基本的な設計指針

マイルストーン

ベータ版までの進捗

ベータ版の想定形式

正式リリースの想定形式

TODO

tao-s commented Feb 6, 2020 •

edited

Loading

okazy commented Feb 7, 2020

pineray commented Feb 9, 2020

okazy commented Feb 19, 2020

okazy commented Feb 19, 2020

okazy commented Apr 9, 2020 •

edited

Loading

okazy commented Apr 20, 2020

nanasess commented Apr 20, 2020

nanasess commented Apr 22, 2020

okazy commented May 29, 2020

atsuyuki-inui commented Jun 9, 2020

okazy commented Jun 11, 2020

atsuyuki-inui commented Jun 11, 2020

okazy commented Jul 1, 2020

okazy commented Jul 1, 2020

Web API仕様 #4447

Web API仕様 #4447

Comments

kiy0taka commented Jan 22, 2020 • edited by okazy Loading

概要(Overview)

API仕様

Query

Mutation

認可

Webhooks

kiy0taka commented Jan 22, 2020 • edited Loading

okazy commented Jan 23, 2020

nanasess commented Jan 23, 2020

okazy commented Jan 29, 2020 • edited Loading

ニュース

基本的な設計指針

マイルストーン

ベータ版までの進捗

ベータ版の想定形式

正式リリースの想定形式

TODO

tao-s commented Feb 6, 2020 • edited Loading

okazy commented Feb 7, 2020

pineray commented Feb 9, 2020

okazy commented Feb 19, 2020

okazy commented Feb 19, 2020

okazy commented Apr 9, 2020 • edited Loading

API開発状況まとめ

リリーススケジュール

APIの仕様

GraphQL Mutationの仕様(案)

懸念

変更履歴

okazy commented Apr 20, 2020

EC-CUBE4 Web API β フィードバック

nanasess commented Apr 20, 2020

nanasess commented Apr 22, 2020

okazy commented May 29, 2020

APIプラグイン化に向けた課題

atsuyuki-inui commented Jun 9, 2020

okazy commented Jun 11, 2020

atsuyuki-inui commented Jun 11, 2020

okazy commented Jul 1, 2020

okazy commented Jul 1, 2020

kiy0taka commented Jan 22, 2020 •

edited by okazy

Loading

kiy0taka commented Jan 22, 2020 •

edited

Loading

okazy commented Jan 29, 2020 •

edited

Loading

tao-s commented Feb 6, 2020 •

edited

Loading

okazy commented Apr 9, 2020 •

edited

Loading