はじめに
こんにちは、スパイラル株式会社のインターン生です！
今回は、SPIRALのAPIを使ってアプリ開発を進めていく上で、避けて通れない
APIドキュメントの使い方について紹介していきます。
APIドキュメントって何？
「API」とは、アプリやプログラムと外部のサービスをつなぐ架け橋のような存在です。
そして、「APIドキュメント」はその橋を安全に扱うためのトリセツです。
なぜ「使い方」が重要？
APIドキュメントは専門的な情報が多く、初心者はつまづきやすいです。
慣れていないと、
- 専門用語が多く読んでられない...
- 長すぎて、結局何から見ればいいのかわからない...
- サンプルコードの内容が理解できない...
となりがちです。
だからこそ、押さえるべきポイントや使い方のコツを知っておくと、格段に楽になります
SPIRAL APIドキュメントを開いてみよう
まずはこちら↓
▶︎ SPIRAL ver.1 API リファレンス
構成
(1) メソッド一覧（どんな操作ができるか）
(2) 各メソッド・ヘッダー・パラメータの説明
(3) リクエストサンプル・レスポンスサンプル
押さえるべきポイントはここ！
1. メソッド一覧で全体を把握
まずは、メソッド一覧をざっと確認して、何ができるのかを把握しましょう。
- データの登録 / 更新 / 削除 / 検索 など、APIでできることの一覧を確認
- 「自分がやりたいこと」がどこにあるかをチェック
2. リクエストサンプルを真似る
やりたいことが見つかったら、
そのリクエストサンプルを参考に実際にリクエストしてみましょう。
以下は、画像データをSPIRALに登録するリクエストの例です。
{
"spiral_api_token": "取得したトークン",
"passkey": 123456789,
"signature": "署名",
"db_title": "member",
"data": [
{
"name": "imageName",
"value": "base64に変換した画像データ",
"attribute": {
"img_name": "test.png",
"img_content_type": "image/png"
}
}
]
}
リクエストのフォーマットはjson形式です。
上記の内容で、初心者がつまづきやすそうな項目もいくつかあるので、簡単に紹介します：
| 項目 | 概要 | 補足 |
|---|---|---|
signature |
リクエストの正当性を示す「署名」 | サポートサイトに生成方法あり |
spiral_api_token / passkey
|
ユーザーごとに異なる「トークン」や「署名」 | SPIRAL登録後に発行されます |
base64 |
画像を文字列に変換するための規格 | Webツールで簡単に変換できます |
他にも不明点があれば、ドキュメント内に説明されている内容を確認してください。
SPIRALのトライアルは以下のリンクから！
3. レスポンスを読み解く
リクエストを行うとレスポンス（＝結果）が返ってきます。
以下は、先ほどの画像登録のリクエストに対するレスポンス例です。
正常時のレスポンス例
{
"code": 0,
"message": "OK",
"id": 1
}
異常時のレスポンス例
{
"code": 101,
"message": "Invalid API token"
}
codeの値で成功／失敗を判断できます。
エラーコードの詳細はこちらで確認してください。
まとめ
- 全部読もうとする必要はない
- まずはメソッド一覧で全体像を把握
- やりたいことを探し、サンプルを参考にリクエストしてみる
- 色々試してみてリクエストとレスポンスの形式に慣れる
APIを扱う上で、トリセツは重要になってきます。
APIのより詳しい仕様や呼び出し方法などについては、今回は割愛します。
詳しい内容はスパイラルAPIの使い方を確認してください。
参考
最後に
私がインターンしているスパイラル株式会社は、ローコードプラットフォーム、SPIRAL ver.1のトライアルアカウントを無償提供しています。このアカウントの記事でも紹介するように、たくさんの機能ございます。
▶︎ フォーム
▶︎ 認証エリア
▶︎ ログイン
▶︎ メール送信
▶︎ カスタムプログラム
などの作成できますので、ぜひ試してみてください!!
そして、今チームでトライアル登録者向けに、オンボーディングコンテンツを作成しています。SPIRAL ver.1にご興味のある方、ぜひこちらもご覧ください👇