API等の公式マニュアルの正しい読み方が知りたい

「PAY.jp」というサービスがあり以下のようなマニュアルがあります

例えば上記マニュアルを見て
「PHPのSDKを使い顧客リストのJSONデータを取得したい」と思い

■1.APIドキュメント「#顧客リストを取得」を参照すると
https://pay.jp/docs/api/#%E9%A1%A7%E5%AE%A2%E3%83%AA%E3%82%B9%E3%83%88%E3%82%92%E5%8F%96%E5%BE%97

■2.以下のPHPソースで
\Payjp\Payjp::setApiKey("sk_test_XXXXXXXXXXXXXXXX");
\Payjp\Customer::all(array("limit" => 3, "offset" => 10));

■3.以下のようなJSON値が「レスポンス」される　と説明されていますが
{
"count": 1,
"data": [
{
"cards": {
"count": 0,

実際に2のソースを実行してもJSONが「レスポンス」（標準出力）されることはありません
標準出力なんてどこにも書いていないので標準出力しないのだろう、ではレスポンスとは一体なんなのか
標準出力されないので変数に代入してみました

■4.返り値を変数に代入してみる
\Payjp\Payjp::setApiKey("sk_test_XXXXXXXXXXXXXXXX");
$hoge = \Payjp\Customer::all(array("limit" => 3, "offset" => 10));
print_r($hoge);

するとオブジェクト形式が返却され、プロテクトがかかっており
ドキュメント通りのJSONデータにアクセスすることができません
私が期待する結果はJSON形式の値が返ってくることです

Payjp\Collection Object
(
    [_opts:protected] => Payjp\Util\RequestOptions Object
        (
            [headers] => Array
~~~~~~~~~~~省略~~~~~~~~~~~

オブジェクトをJSONに変換する関数などがあるのかと
ドキュメントをはじめから目を通してみたのですが
どこにもそのような言及はありませんでした

エラーメソッドにそれっぽい関数はありましたので
以下を試してみたのですが当然エラーとなりました
$hoge = \Payjp\Customer::all(array("limit" => 3, "offset" => 10))::getJsonBody();
$hoge = \Payjp\Customer::all(array("limit" => 3, "offset" => 10))->getJsonBody();


「レスポンス」という言葉の定義をマニュアル内でキーワード検索しましたが
答えは見つからない

ドキュメントに書かれている通りのJSONを返り値として得たい
こういう場合に「googleを使って」「先人プログラマの具体的なソースが書いてある備忘録のブログを見る」という
問題解決方法が常態化してしまっているのですが

これで解決できてしまうのでその手法に甘えていたのですが
ここらへんで「ちゃんとマニュアルを見る」「公式ドキュメントで理解する」方法を身に着けたいと思っています

このドキュメント通り
\Payjp\Payjp::setApiKey("sk_test_XXXXXXXXXXXXXXXX");
\Payjp\Customer::all(array("limit" => 3, "offset" => 10));

でJSONの値は返ってきません、でもマニュアルには「レスポンス」すると書かれています

私は、ドキュメントのどこを見ればこれを理解することが出来るのでしょうか
コツなのか分からないですが「公式ドキュメントを見て理解できる」方にどうやったら
「先人プログラマの具体的なソースが書いてある備忘録のブログを見る」ではなく
正しいマニュアルの読み方が身に着くのか教えていただきたいです

お忙しいところ恐縮ですがご確認よろしくお願い致します

行動規範の内容に同意します

回答2件

ベストアンサー

自動生成のAPIリファレンスはわかりにくい。あまり役に立たない。
ドキュメントとGitHubを見るほうが多い。
ググるのは一番無駄。

APIからのレスポンスがjsonだとしても各言語のSDKでどう扱ってるかは別。
https://github.com/payjp/payjp-php/blob/8902fb85bbbaeb6b3eefbad39755a2117e302280/lib/Customer.php#L29

php
1    /**
2     * @param array|null $params
3     * @param array|string|null $opts
4     *
5     * @return array An array of Customers.
6     */
7    public static function all($params = null, $opts = null)
8    {
9        return self::_all($params, $opts);
10    }

@return arrayだけど実際に動かすとPayjp\CollectionならGitHubのほうが間違ってる。
https://github.com/payjp/payjp-php/blob/master/lib/Collection.php
Collection→ApiResource→PayjpObjectと辿っていくと
PayjpObjectはarrayのように使えるはずなので
$hoge['data']や$hoge->dataができそう。
jsonにするなら。

$json = $hoge->__toJSON();

PHP5.6以上のせいかこのSDK自体が現代のPHPでは辛い。
結局はドキュメントもSDKも整備されてないので使いにくいのは当然。

投稿2021/06/21 15:51

kawax

総合スコア10377

tesopgmh

2021/06/21 16:51

すごい、すごいです！ WEBで具体的なソース書いてる人たちってkawaxさんみたいな人たちなんですよね本当にすごいと思います $json = $hoge->__toJSON(); で出来ました！！なんでこれを導き出せるんですか！？「function all」でソース全体をgrep検索して、くらいは私でも理解できますがそこからextendされてるソースをたどるとなんで正解があると分かったんでしょうか？？経験則ですか？？ kawax様が答えを導き出してるときの頭の中のロジックめちゃくちゃ見たいです最終地点に「public function __toJSON()」があるので $json = $hoge->__toJSON(); は分かりましたが PayjpObjectはarrayのように使えるはずなので $hoge['data']や$hoge->dataができそう。これがどのように導き出されたのかもいまだに分かってないですありがとうございます！！

行動規範の内容に同意します