API仕様書の項目を考える

API仕様書を書くことになったものの、外部のツールは規定で使えない。
これといったテンプレートも用意されていないため、どうしたもんかなあ。API開発したことないし…。
ってことで、いろいろと調べてから考えてみた。


はてなブックマーク済み

そういえばはてなブックマーク済みの中にAPIに関するものがあった。

speakerdeck.com
speakerdeck.com
speakerdeck.com

すでに作成されているAPIは、取得でも全部POSTメソッドだったから、REST思考ではないってことを理解した。
内部向けのAPIだからなんだろうな。


api 叩く url」でググる

"GET /search/API仕様書"と"/search?q=API仕様書"は同じ呼び出し方???とかこの辺で混乱したので「api 叩く url」でググった。

下記の記事、内容が充実してた。
WebAPIについての説明 - Qiita

あと、HTTPの知識が弱いってことを自覚した。雰囲気しか分かってない。アカン…。


api 仕様書 サンプル」でググる

そして本題をググった。

下記の記事がパッと見で分かりやすかった。
API仕様書に書いて欲しい内容 - @peccul is peccu


API仕様書の項目

これでイケるかなあ。

  • 処理概要
  • アクセスURL
  • (プロトコル)
  • メソッド(GET/POST/PUT/DELETE)
  • リクエス
    • (形式(JSON など))
      • No.
      • 名前(例:article_id)
      • 型(数値/文字列 など)
      • 長さ
      • 必須(必須/任意)
      • 内容(例:記事ID)
      • 備考
  • レスポンス
    • 形式(JSON など)
      • No.
      • 名前(例:author)
      • 型(数値/文字列 など)
      • 長さ
      • 繰返し(○/回数/空欄 など)
      • 内容(例:記者)
      • 備考
    • (サンプル)

URLとURIの違いも調べたけどぼんやりとした感じ。
積んでる「Webを支える技術」と、「Web API: The Good Parts」を読んで知識を身につけるべきだな…。

Alexaスキル開発の道のり

dosomething.hatenablog.com

前回調査したAlexaスキル開発、実際に試してみました。


流れ

アカウントをつくるところからやっていきます。
私は3時間でシミュレーションでサンプルが動くところまでいけました。
AWSの初期設定でもたつかなければ30分くらい少なくみてもいいかも。

  1. Amazon Developer アカウントを作成する
  2. AWSの無料アカウントを作成する
  3. AWSの初期設定を行う
  4. Alexaスキル開発

Amazon Developerアカウントを作成する

"Alexa Skills Kit"を使うためには、Amazon Developerアカウントが必要です。

Amazon 開発者ポータル
サインインAmazon Developerアカウントを作成

2018/01/21 追記
Amazon Developerアカウントを作成」でアカウントを作成すると、Amazon Echo実機でのテストができなくなるという記事を確認しました。
Amazon.co.jpのアカウントとパスワードでサインインしてAmazon Developerアカウントを作成することが推奨されているようです。

【参考】
失敗しないAlexa開発者アカウントの作り方 | Developers.IO
Alexa 開発者アカウントのハマりどころ - Qiita

必須項目を入力してアカウントを作成します。

AWSの無料アカウントを作成する

Alexaスキル開発は"AWS Lambda"というAWSのサービスを利用すると簡単に取り組めます。

【準備するもの】クレジットカード(無料アカウントですが、登録は必須です)

AWS アカウント作成の流れ | AWS
上記のフローを確認しながら、アカウントを作成します。

【補足】

  • アカウントの種類は「パーソナル」にしました
  • AWSは名前だけでなく、住所も英語で入力してください

AWSの初期設定を行う

AWSアカウントを取得したら速攻でやっておくべき初期設定まとめ - Qiita

私はもう最初の最初にやっておこうと思ってやりましたが、先を急ぐのであればここはすっ飛ばしてもいいはず。

【備考】

  • 「お支払通貨の設定」を「円」に変更する場合、 VisaかMasterCardがデフォルトの支払方法でなくてはならない

Alexaスキル開発

Alexa Blogsの次の記事のステップ2から取り組んでいきます。
Alexaスキル開発トレーニングシリーズ 第1回 初めてのスキル開発 : Alexa Blogs

【補足】

  • 「.ZIPファイルをアップロード」するだけでできます。AWS Lambda使ったことないけど、とりあえず試したい人にはうってつけ。
  • キャプチャと現行の画面が異なる箇所が多いです。
  • トリガーの設定で"Alexa Skills Kit"を選んだ後、右下の「追加」を押すのを忘れない

せっかくだしシミュレータだけじゃなくて実機で試してみたいなあ。

Alexaスキル開発について、調査中

前提知識

Amazonエコー」「アレクサ」「スキル」といった単語そのものがピンとこなかったので、まずはここから。

Amazon Echo」はAmazonスマートスピーカー

Amazon | Echo - スマートスピーカー
招待がないと購入できない。

参考になりそうなWebページ

ブログ・Qiita

日本語のAlexaスキルの作り方(30分あればAmazon Echoがなくても試せるよ) - KAYAC engineers' blog
Amazon Echo (Alexa) のSkillの開発に必要な基本概念を押さえる - Qiita
Amazon Echo Dotで物忘れを克服する - Qiita
Amazon EchoのSkillで何かを作ってみて申請してみる - Qiita
Amazon EchoのSkillで何かを作ってみて申請してみたら申請結果が返ってきた - Qiita

Alexa Skill を設計する前にすれば良かったと思ったこと - Qiita
Alexaのカスタムスキルを設計するときのTipsまとめ - Qiita

このVUI設計の話を読んで思い出したこと(蛇足)

昔(数年前かなあ)、携帯電話の操作を音声のみで行うための実験映像をテレビで見たことを思い出した。日本の携帯電話会社がやってたやつ。
携帯電話を操作していたのは中年の女性で、音声操作でメールを送信するという実験をしていた。
ただ、その人はいきなりメール本文を話し出してしまい、想定の音声操作をしなかったという結果に終わったというやつ。
開発者の想定は、確か最初にメールの操作をすることと、送信する相手を言うことになってたみたいだけど。

『職場の問題地図』を読んで思ったこと

『職場の問題地図』を読み終えた。
gihyo.jp


なぜ読んだのか

↓の参考本で見つけて気になったから。
ITエンジニアに読んでほしい!技術書・ビジネス書 大賞2018

このタイトルで目が止まったのは、会社のことで不満がたまってたせいなんだろうな…。


読了にかかった時間

合計1時間40分。1章あたり5~15分程度で読めた。


所感

報連相設計は意識したことなかった。
そこそこいろいろな人のもとで仕事をしてきて、「依頼内容」、「クライアント(社内用とかお客様向けとか、本書でいうところのラスボス)」、「目的(認識合わせ用とか、事前調査とか)」、「期限(これ大事なのに意外と上司サイドから提示されない)」は意識して尋ねてきたつもりだけど。
報連相の頻度とタイミングの合意をとることも今後意識したいと思った。

なんかでもなあ。報連相は求められるけど、成果物は完成してからはじめて見るから、手戻りが多い。
それ見越して期限よりも早めに出したら、そうじゃなくて!と強く言われて、恐らく向こうはそんなつもりじゃないんだろうけど怒られてる気分で、修正のモチベーションが下がったことがあった。
本書であったポンチ絵がこれを防ぐ策なんだろうけど、このポンチ絵を作るのに時間がかかりすぎちゃうとまた怒られそうな気がした。
このあたりは要トレーニングかな。時間のかけ方とかクオリティとか…。


見積もりの話は目を背けたくなる内容だった。野生のカン頼み(経験と感覚)で仕事してる…。


属人化については、「私が辞めてもマニュアルがあるもの」を目指したい。


部下よりも上司に向けた内容が多い印象。
こういうことすると部下のモチベーション下がっちゃうよ!って記述が所々にある。部下のいない下っ端の私からすると「うんうんそうなんだよ!」って納得できる内容ばかりだった。
ただなあ、部下からみた上司の悪いところが上司に伝わることってほぼないと思う(嫌なら部下が去る)ので、自覚すらしてないと思う…自覚してないとカイゼン行動とらないと思うんだよな…。

所感が愚痴じみてしまったが、まずは自分にできるカイゼン行動をとっていきたいと思う。

これからやりたいことと2017年の振り返り

やりたいこと

コミュニティへの参加

コミュニティが会社だけというのは厳しいので勇気があれば参加したい

LT登壇

やった方がいいよってどこ行っても言われているし、勇気があれば…

積読消化

いっぱい買ってあるので、量をこなす意味でも、ペースを上げたい

応用情報技術者の資格取得

2018年こそは!

持ち運びに便利な端末の購入

勉強会やセミナーに行く時の端末の持ち運びを楽にしたい

眼鏡の買い替え

フレームのメンテナンスをせずに8年近く使い続けている運転用の眼鏡を買い替えたい。
度入りのサングラスで検討。

電子書籍への切り替え

本の置き場がなくなってきたので、検討したい


今後も続けたいこと

勉強会やセミナーへ足を運ぶ

足を運ぶだけでも刺激になります。
参加エントリを書くことと、Togetterでまとめを作ることはセットで。

情報収集

はてなブックマークIPA、JPCERT、トレンドマイクロのセキュリティブログの平日チェックがキャッチアップ

歯科検診に通う

2014年秋から3か月間隔で歯科検診に通っています。
この間隔でも小さな虫歯ができて治療になることもあります。

定期的な運動

週に1回以上はゲーセンに行って、DDRやダンエボといった運動できるゲームをやってます。
2015年12月から続けている唯一の運動です。


2017年の箇条書き振り返り

  • お客様先常駐、出張先、自社と、様々な環境で仕事をさせていただいた
  • 都会の勉強会に初めて足を運んだ
  • ドキュメント作成のお仕事が多かった


今も抱えているので、ストレスの少ない取り組み方を見つけたい

  • プロジェクトマネジメント研修を受けて、プロジェクトマネジメントやりたいって気持ちを失った
  • 出張先の観光をぼっちで楽しんだ

今抱えている不満に向き合って解決できれば、きっと次のステージに行けると信じて、もがいてみたいと思います。本当にだめだったら、その時は逃げることも視野に入れて。

スイッチ?チェックボックス?どちらが妥当?

本日12月29日が仕事納めの私です。
お客様と認識を合わせるための、スマートフォンアプリの画面資料を作成しておりました。
iOSベースで考えていたのですが、はて、ここはスイッチ(トグル)とすべきか、チェックボックスとすべきかで悩ましい項目が出てきました。
こんな時はグーグル先生、ということで「スイッチ チェックボックス」でググったところ、まさにドンピシャの記事が見つかりました。

正しく使えてる? チェックボックスとスイッチの使い分け | UX MILK
submitで反映する場合→チェックボックス
即時反映→スイッチ

ということで上記考えに基いてチェックボックスで資料を作成したのですが、「iOSの機能使えるんだから使って」と一蹴されてしまいました…。
submitで反映するというのもあるのですが、選択項目が5個以上あるし、Androidアプリも開発見込みだし、正直チェックボックスの方が良いと思ったのになあ。
そう思いつつ、資料を修正したのでした。

MySQLをコマンドで操作する

先週からスマートフォンアプリ案件のテストやドキュメント作成をしています。ず~っとWebアプリ案件に携わってきたので新鮮な気持ちです。
そこで、DBには保存してるけどアプリ側では見る術がなく、テストで確認しないといけない都合上、MySQLのDBをコマンド操作しているため、コマンドの備忘録です。

MySQL :: MySQL 5.6 リファレンスマニュアル
↑日本語リファレンスマニュアル最新?

接続・切断

MySQL :: MySQL 5.6 リファレンスマニュアル :: 3.1 サーバーへの接続とサーバーからの切断

接続

$ mysql -D database -u user -p

※"D"は大文字

Enter password:

上記のように表示されたら、パスワードを入力する。
以下のように表示されたらOK

mysql> 

切断

mysql> QUIT

以下のように表示されたらOK

Bye

SELECTの可読性を上げる

mysql> select * from table1;
+----+-----------+
| id | deleteflg |
+----+-----------+
|  1 | 1         |
|  2 | 1         |
+----+-----------+

このくらいだったらまだ分かるけど、カラムが多いと表示が崩れて可読性が下がる。
そんな時は";"の代わりに"\G"。

mysql> select * from table1\G
*************************** 1. row ***************************
       id: 1
deleteflg: 1
*************************** 2. row ***************************
       id: 2
deleteflg: 1

mysql select 整形』でググってたどり着きました↓
ちょっと変えるだけでMySQLの検索結果が格段に見やすくなる方法 | アイビースター

テーブルに関する情報の取得

MySQL :: MySQL 5.6 リファレンスマニュアル :: 3.4 データベースとテーブルに関する情報の取得

データベースのテーブル名リスト取得

mysql> SHOW TABLES;
+----------------------------------+
| Tables_in_database               |
+----------------------------------+
| table1                           |
| table2                           |
+----------------------------------+
2 rows in set (0.01 sec)

テーブル情報取得

mysql> DESCRIBE table1;
+-----------+-------------+------+-----+---------+----------------+
| Field     | Type        | Null | Key | Default | Extra          |
+-----------+-------------+------+-----+---------+----------------+
| id        | int(11)     | NO   | PRI | NULL    | auto_increment |
| deleteflg | char(1)     | NO   |     | 0       |                |
+-----------+-------------+------+-----+---------+----------------+
2 rows in set (0.00 sec)

インデックス情報取得

これは前にWebアプリ案件でOracleSQLチューニング(インデックスとかヒント句とか)を依頼されたけど、知識のなさと試せる環境になかった(定義のドキュメントしかなかった)のとで、後から大幅修正されてたことが悔しくて、チューニング周りをいつかちゃんと習得したくて書きました。

MySQL :: MySQL 5.6 リファレンスマニュアル :: 13.7.5.23 SHOW INDEX 構文

mysql> SHOW INDEX FROM table1;
+--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+
| Table  | Non_unique | Key_name | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Index_comment |
+--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+
| table1 |          0 | PRIMARY  |            1 | id          | A         |          24 |     NULL | NULL   |      | BTREE      |         |               |
+--------+------------+----------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+---------------+
1 rows in set (0.00 sec)

それにしてもdeleteflg="1"のレコードがinsertされてることを不思議に思って、製造者に確認したら、これどうも"予約"らしい。
"deleteflg"より"state"の方がいいのでは?とも思ったし、開始日時・終了日時登録されてるからこのカラムそのものもいらないのでは?と思った。(上記の例で出したテーブルはもっとカラムあるけど、ブログ用に省略してある)
まあ確かにこちらのお客様の別アプリ案件でもそんなDB設計だった覚えはあるけど、まさかそれが引き継がれているとは…と悲しい気持ちになった。
DB設計も勉強したいことのひとつではある。勉強したいことは多いのだが、最近どうもメンタルが弱って何もできていない。まずは早く心身ともに元気になりたい…