Zenn
🙌

Sumaregi-go: GoでのSumaregi APIクライアントライブラリ開発入門 (Part 3)

2024/09/16に公開
Go
API
tech

1. はじめに

前回の記事では、Sumaregi APIと対話するためのクライアントの設計と実装について説明しました。また、クライアントの初期化方法、APIエンドポイントへのリクエストの送信方法、エラーハンドリングについても詳しく解説しました。今回は、このクライアントを使ってSumaregi APIのエンドポイントにリクエストを送信する具体的な例として、取引データを取得する関数GetTransactionsと取引の詳細を取得する関数GetTransactionDetailを説明します。それぞれの関数がどのようにSumaregi APIとやり取りするのか、そしてどのようにリクエストとレスポンスのデータを処理するのかを見ていきます。

2. 対象読者

この記事は、Sumaregi APIを使って取引データを操作したい開発者を対象としています。前回までの記事を読んでクライアントの基本的な設計と実装を理解していることを前提としています。また、GoでのHTTPリクエストやJSONデータの処理に関する基本的な知識があると、この記事の内容をよりスムーズに理解できます。

3. 記事を読むメリット

この記事を読むことで、以下のメリットがあります：

  • GetTransactions関数の実装を理解し、Sumaregi APIから取引データを取得する方法を学べる
  • GetTransactionDetail関数を使用して特定の取引の詳細を取得する方法を理解できる

これらの知識を習得することで、Sumaregi APIを使った高度なデータ操作が可能となり、アプリケーション開発の幅が広がります。

4. 本文

1. GetTransactions関数

GetTransactions関数は、Sumaregi APIから取引データを取得するためのメソッドです。この関数では、クエリパラメータを使ってリクエストをカスタマイズし、取引データを取得します。

func (c *Client) GetTransactions(ctx context.Context, opts GetTransactionsOpts) (*GetTransactionsResponse, error) {
    var result GetTransactionsResponse

    v, err := query.Values(opts)
    if err != nil {
        return nil, err
    }
    err = c.call(ctx, APIPathTransactions, http.MethodGet, v, nil, &result)
    if err != nil {
        return nil, err
    }

    return &result, nil
}

  • 引数:

    • ctx: リクエストのコンテキスト。
    • opts: 取引データを取得するためのオプションを格納するGetTransactionsOpts構造体。

  • 処理の流れ:

    1. optsをクエリパラメータに変換します。query.Values(opts)を使用して、構造体からURLクエリ文字列を生成します。
    2. callメソッドを使ってAPIにGETリクエストを送信します。クエリパラメータとリクエストパス（APIPathTransactions）を指定します。
    3. APIからのレスポンスをGetTransactionsResponse構造体にデコードします。
    4. デコードしたデータを返します。

この関数を使用することで、Sumaregi APIから取引データを簡単に取得できます。optsを使うことで、取得するデータを必要に応じてフィルタリングしたり、ソートしたりできます。

2. GetTransactionDetail関数

GetTransactionDetail関数は、指定された取引IDに対応する取引の詳細を取得します。

func (c *Client) GetTransactionDetail(ctx context.Context, opts GetTransactionDetailOpts, id string) (*GetTransactionDetailResponse, error) {
    var result GetTransactionDetailResponse
    v, err := query.Values(opts)
    if err != nil {
        return nil, err
    }

    err = c.call(ctx, path.Join(APIPathTransactions, id, "details"), http.MethodGet, v, nil, &result)
    if err != nil {
        return nil, err
    }

    return &result, nil
}

  • 引数:

    • ctx: リクエストのコンテキスト。
    • opts: 詳細データの取得に使用するオプションを格納するGetTransactionDetailOpts構造体。
    • id: 取得したい取引のID。

  • 処理の流れ:

    1. optsをクエリパラメータに変換します。
    2. callメソッドを使用してAPIにGETリクエストを送信します。取引IDを含むリクエストパス（APIPathTransactions/{id}/details）を指定します。
    3. APIからのレスポンスをGetTransactionDetailResponse構造体にデコードします。
    4. デコードしたデータを返します。

この関数を使用することで、特定の取引に関連する詳細情報を簡単に取得できます。たとえば、取引に関連する商品のリストやその属性など、詳細な情報を取得できます。

5. コード例

以下は、transactions.goファイルの完全なコードです。

package sumaregi

import (
	"context"
	"net/http"
	"path"

	"github.com/google/go-querystring/query"
)

const (
	APIPathTransactions = "transactions"
)

func (c *Client) GetTransactions(ctx context.Context, opts GetTransactionsOpts) (*GetTransactionsResponse, error) {
	var result GetTransactionsResponse

	v, err := query.Values(opts)
	if err != nil {
		return nil, err
	}
	err = c.call(ctx, APIPathTransactions, http.MethodGet, v, nil, &result)
	if err != nil {
		return nil, err
	}

	return &result, nil
}

func (c *Client) GetTransactionDetail(ctx context.Context, opts GetTransactionDetailOpts, id string) (*GetTransactionDetailResponse, error) {
	var result GetTransactionDetailResponse
	v, err := query.Values(opts)
	if err != nil {
		return nil, err
	}

	err = c.call(ctx, path.Join(APIPathTransactions, id, "details"), http.MethodGet, v, nil, &result)
	if err != nil {
		return nil, err
	}

	return &result, nil
}

6. まとめ

この記事では、Sumaregi APIと対話するためのクライアントを使って取引データとその詳細を取得する方法を説明しました。GetTransactions関数を使うことで、取引のリストを取得し、GetTransactionDetail関数を使うことで、特定の取引の詳細を取得できます。これにより、Sumaregi APIを使った取引データの操作がより容易になります。

Discussion