APIのトリセツを使いこなそう 〜SPIRAL APIドキュメント読解入門〜

https://www.pi-pe.co.jp/regist/is?SMPFORM=man-lanerf-2473a633d82734eb22aa64cad426ae23&utm_source=pup-qiita&utm_medium=contentlink&utm_campaign=/SPIRAL_internship/items/d555c666a2da836f1098&utm_content=link-top&f000099824=https://qiita.com/SPIRAL_internship/items/d555c666a2da836f1098

---
## はじめに
こんにちは、スパイラル株式会社のインターン生です！
今回は、SPIRALのAPIを使ってアプリ開発を進めていく上で、避けて通れない
**APIドキュメントの使い方**について紹介していきます。
 
## APIドキュメントって何？
「API」とは、アプリやプログラムと外部のサービスをつなぐ**架け橋**のような存在です。
そして、「APIドキュメント」はその橋を安全に扱うための**トリセツ**です。
 
## なぜ「使い方」が重要？  
APIドキュメントは専門的な情報が多く、初心者はつまづきやすいです。
慣れていないと、
 
- 専門用語が多く読んでられない...
- 長すぎて、結局何から見ればいいのかわからない...
- サンプルコードの内容が理解できない... 
 
となりがちです。  
 
だからこそ、**押さえるべきポイント**や**使い方のコツ**を知っておくと、格段に楽になります
 
## SPIRAL APIドキュメントを開いてみよう
 
まずはこちら↓
▶︎ [SPIRAL ver.1 API リファレンス](https://support.smp.ne.jp/api/)  
 
### 構成
(1) メソッド一覧（どんな操作ができるか）
(2) 各メソッド・ヘッダー・パラメータの説明
(3) リクエストサンプル・レスポンスサンプル
 
 ![](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4041448/fdd53a89-c044-45d8-836a-3992b00626fa.png)
 
##  押さえるべきポイントはここ！
### 1. メソッド一覧で全体を把握
まずは、メソッド一覧をざっと確認して、**何ができるのか**を把握しましょう。
- データの登録 / 更新 / 削除 / 検索 など、APIでできることの一覧を確認
- 「自分がやりたいこと」がどこにあるかをチェック
 
### 2. リクエストサンプルを真似る
やりたいことが見つかったら、
その**リクエストサンプルを参考**に実際にリクエストしてみましょう。
以下は、画像データをSPIRALに登録するリクエストの例です。
```json
{
  "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`| リクエストの正当性を示す「署名」 | [サポートサイト](https://support.smp.ne.jp/api-manuals/spiral_api/#signature)に生成方法あり |
| `spiral_api_token` / `passkey` | ユーザーごとに異なる「トークン」や「署名」 |SPIRAL登録後に発行されます|
| `base64`|画像を文字列に変換するための規格| Webツールで簡単に変換できます|
 
他にも不明点があれば、[ドキュメント](https://support.smp.ne.jp/api/)内に説明されている内容を確認してください。

---
SPIRALのトライアルは以下のリンクから！

https://www.pi-pe.co.jp/regist/is?SMPFORM=man-lanerf-2473a633d82734eb22aa64cad426ae23&utm_source=pup-qiita&utm_medium=contentlink&utm_campaign=/SPIRAL_internship/items/d555c666a2da836f1098&utm_content=link-middle&f000099824=https://qiita.com/SPIRAL_internship/items/d555c666a2da836f1098

---
 
### 3. レスポンスを読み解く
リクエストを行うとレスポンス（＝結果）が返ってきます。
以下は、先ほどの画像登録のリクエストに対するレスポンス例です。
 
#### 正常時のレスポンス例
```json
{
  "code": 0,
  "message": "OK",
  "id": 1
}
```
 
#### 異常時のレスポンス例
```json
{
  "code": 101,
  "message": "Invalid API token"
}
```
`code`の値で**成功／失敗**を判断できます。
エラーコードの詳細は[こちら](https://support.smp.ne.jp/api-manuals/errorcode_api/)で確認してください。
 
## まとめ
- 全部読もうとする必要はない
- まずはメソッド一覧で全体像を把握
- やりたいことを探し、サンプルを参考にリクエストしてみる
- 色々試してみてリクエストとレスポンスの形式に慣れる
 
APIを扱う上で、トリセツは重要になってきます。
APIのより詳しい仕様や呼び出し方法などについては、今回は割愛します。
詳しい内容は[スパイラルAPIの使い方](https://support.smp.ne.jp/api-manuals/spiral_api/)を確認してください。
 
## 参考
- [SPIRAL ver.1 API リファレンス](https://support.smp.ne.jp/api/)
- [APIリファレンスの読み方](https://support.smp.ne.jp/api-manuals/how_to_read_api_ref/)
- [スパイラルAPIの使い方](https://support.smp.ne.jp/api-manuals/spiral_api/)
 
## 最後に
私がインターンしているスパイラル株式会社は、ローコードプラットフォーム、SPIRAL ver.1の**トライアルアカウント**を**無償提供**しています。このアカウントの記事でも紹介するように、たくさんの機能ございます。
 
▶︎ フォーム
▶︎ 認証エリア
▶︎ ログイン
▶︎ メール送信
▶︎ カスタムプログラム
 
などの作成できますので、ぜひ試してみてください!!
 
https://www.pi-pe.co.jp/regist/is?SMPFORM=man-lanerf-2473a633d82734eb22aa64cad426ae23&utm_source=pup-qiita&utm_medium=contentlink&utm_campaign=/SPIRAL_internship/items/d555c666a2da836f1098&utm_content=link-bottom&f000099824=https://qiita.com/SPIRAL_internship/items/d555c666a2da836f1098
 
そして、今チームでトライアル登録者向けに、オンボーディングコンテンツを作成しています。**SPIRAL ver.1**にご興味のある方、ぜひこちらもご覧ください👇
 
https://knowledge.spirers.jp/special/detail/11680