Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Web API仕様 #4447

Open
kiy0taka opened this issue Jan 22, 2020 · 10 comments
Open

Web API仕様 #4447

kiy0taka opened this issue Jan 22, 2020 · 10 comments

Comments

@kiy0taka
Copy link
Contributor

@kiy0taka kiy0taka commented Jan 22, 2020

概要(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に合わせて以下の情報が変更された場合に通知する。

  • 商品情報
  • 受注情報
  • 会員情報
@kiy0taka

This comment has been minimized.

Copy link
Contributor Author

@kiy0taka kiy0taka commented Jan 22, 2020

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

@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Jan 23, 2020

3系Issueはこちら
#1530

@nanasess

This comment has been minimized.

Copy link
Contributor

@nanasess nanasess commented Jan 23, 2020

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

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

@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Jan 29, 2020

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

進捗

ニュース

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

基本的な設計指針

マイルストーン

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

ベータ版までの進捗

  • 実装

  • テスト・レビュー

  • ベータ版リリース

  • 取得(Query)

    • API Platformの検証
    • webonyx/graphql-phpの導入
    • 取得可能データ
      • 商品一覧
      • 受注一覧
      • 会員一覧
    • API定義は、Entityの定義に依存する
    • DBの動作確認
      • PostgreSQL
      • MySQL
      • SQLite
  • 認証・認可(OAuth 2.0 + Open ID Connect)

    • oauth2-bundleの組み込み
      • authorizeエンドポイント(MUST)
        • 認証開始時にアクセスするエンドポイント。 oauth2-bundle の導入で作成される。
      • tokenエンドポイント(MUST)
        • アクセストークン取得時にアクセスするエンドポイント。 oauth2-bundle の導入で作成される。
      • tokenInfoエンドポイント
        • oauth2-bundle では初期で未実装。ベータ版には入らない。
      • UserInfoエンドポイント
        • oauth2-bundle では初期で未実装。ベータ版には入らない。
    • OAuth2.0
    • 認証の状態によるAPIの接続制御
    • CSRF対策(state パラメータ?)
    • ブラウザでのUI
  • 実装したこと、まだできないことの明確化(issue化?)

  • βのスコープ外

    • 更新(Mutation)
    • プラグインでの拡張
    • Webhooks
      • 以下の情報が更新されたタイミングでPOST
        • 商品情報
        • 受注情報
        • 会員情報
      • Webhooksは管理画面から登録可能
      • POST内容の仕様検討(基本的には更新の通知が目的のため何も送信しない想定)
      • タイムアウトなどの仕様検討

ベータ版の想定形式

  • 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

This comment has been minimized.

Copy link
Contributor

@tao-s tao-s commented Feb 6, 2020

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

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

@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Feb 7, 2020

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

@pineray

This comment has been minimized.

Copy link

@pineray pineray commented Feb 9, 2020

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

@okazy okazy mentioned this issue Feb 19, 2020
12 of 17 tasks complete
@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Feb 19, 2020

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

@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Feb 19, 2020

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

@okazy

This comment has been minimized.

Copy link
Contributor

@okazy okazy commented Apr 9, 2020

API開発状況まとめ

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

リリーススケジュール

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

APIの仕様

  • 4.0.x系のプラグインとしてリリース
  • OAuth2.0
  • GraphQL
    • Query
      • #4447 (comment)
      • 取得できるデータ: 商品一覧、受注一覧、会員一覧
      • それぞれの一覧画面で指定できる検索条件で絞ることが可能
      • [残課題] 日付の取得、ページング、出荷時間による検索
    • Mutation
      • 登録できるデータ: 商品登録、受注登録、会員登録
      • それぞれの登録画面で登録できる項目が登録可能

想定しているユースケース

  • GraphQL
    • Query
      • 商品の在庫情報
        • 検索条件: 全商品、商品ID
        • 取得項目: 商品
      • 出荷対象の受注を取得
        • 検索条件: 出荷日、注文日
        • 取得項目: 受注
      • 会員の購入履歴の取得
        • 検索条件: 全会員、会員ID
        • 取得項目: 会員
    • Mutation
      • 商品の在庫を更新
        • Key: 商品規格ID
        • Value: 在庫数、無制限フラグ
      • 新規受注の作成
        • 検討中
      • 受注を出荷済みに更新
        • Key: 出荷ID
        • Value: 出荷日
      • 会員のポイントを更新
        • Key: 会員ID
        • Value: 所有ポイント

懸念

  • 4.0.3では対応できない部分が出てこないか
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.