備忘録

なんとなく暇なときにでも....

初のAPI実装を行っての反省点

会社で初めて規模が比較的大きめのAPI実装を行いました。

大規模なAPI実装自体は、個人でアプリ開発を行った際は、すべて1人で行ったのですが、
そのときは、アプリ側からのリクエストに対して、正しいレスポンスをすることだけしか考えてませんでした。
それに加えて、その際は、自分の隣にアプリエンジニアがいて、意思疎通を取りながらできていたので、認識のズレが少なくて済んでました。

今回ははじめてアプリエンジニアと新機能企画者とAPIエンジニアのように役割が分担されたケース(1番よくありそうなケースですが...)で、 私にとっては初仕事でした。


今回の実装で大きな反省点は2つです。

  • レスポンスの型を意識する

  • アプリ側で実装された完成型もイメージする

レスポンスの型を意識する

まず1つ目は、アプリ側へのレスポンスするときの型についてです。
私は、個人でも会社でもPHPをメインにAPIの実装を行っています。
ここで問題となるのが、"型"についてです。
正直に言いますと、動的型付き言語であるPHPが9割5分を占めている私のエンジニア人生において、型というものを意識する機会は皆無でした。
$a = 1$b = "1"も私にとっては大きく違いがあるものというイメージがありませんでしたが、開発現場ではそうもいかないようです。
アプリ側からのリクエストに対しても、API側で型のチェックを行っています。これは、誤った型でリクエストが渡ってきた場合に一見動いているように見えるという状況を防ぐためでもあります。
たとえば、

$get = $_GET;

$use_id = $get['user_id'];

とした場合。
$user_idは、API側ではinteger型を期待してるのに、もしかしたら、string型でリクエストが来てるかもしれないですよね。

もしものためにバリデーションしておきますが...

$get = $_GET;

$use_id = intval($get['user_id']);

アプリ→APIのようなリクエストの際に、ある特定の型を期待しているのと同様に、
API→アプリのレスポンスの際にも、アプリ側は、(バリデーションをかけているとはいえ)ある特定の型を期待していることでしょう。

ということで、レスポンスの内容が、正しいからといって、そこで終わりではなく、アプリエンジニアとのきちんと型についても意識を共有しておくことが大事だという反省点でした。

もう1つが、レスポンスの際の内容がなかった場合(たとえば、ユーザーのフォロワーを返すようなAPIに対して、user_id = 1のフォロワーが1人もいなかった場合)
この場合レスポンスをどうするべきかということ。

$get = $_GET;

$use_id = intval($get['user_id']);

$follower_data_array = $this->get_follwer($user_id)

return $follower_data;

この例で言うならば、フォロワーがいる場合、フォロワーを返すAPIは、複数の各フォロワー情報を含んだ配列を返すはずです。

$follower_data = array(
    array( 
        user_id  = 2,
        name     = 'AAA',
    ),
    array( 
        user_id  = 5,
        name     = 'BBB',
    ),
    ........
);

しかし、最初に述べたように、user_id = 1のフォロワーが誰もいなかった場合、どのようなレスポンスを返すべきなのでしょうか。
考えられるパターンとしましては、

  1. $follower_data=NULL; で返す

  2. $follower_data=array();(空配列) で返す

  3. 1と2のどちらも許容する

のようなパターンが考えられるかと思われます。
ここでもアプリ側が期待しているものに絞るべきです。
でないとアプリ側の実装の際に、不必要なバリデーションが増えてしまい、冗長ですよね。
1か2が妥当だと思います。(NULLを許容しない2がいいらしい。)

アプリ側で実装された完成型もイメージする

2つ目は、完成型をイメージするということですが、たとえば、あるリクエストに対して、所定のテーブルから、指定のIDの画像のURLを取ってきて返す。といったAPIがあるとします。
しかし、まだ指定された画像が準備おらず、そのレコードの画像URLののカラムがNULLになっています。

このようなケースですが、私は特に意識しておらず、画像のURLもいつか準備されてるだろうから、とりあえずはNULLを返しておけばいいかと思っていました。
しかし、アプリエンジニアからすると、NULLが返ってくるので、実際の画像が表示できず困ってしまうようです。
もう少し、アプリでの実装過程もイメージして、仮の画像を準備するなどして、対処するべきでした。


以上2点が今回の反省点です。
新人エンジニアの人はそこらへんも注意して、API実装を行ってみてはどうでしょうか。


本日はここまで。


参考

qiita.com



Twitterもフォローしてください

twitter.com