# API

## 概要

API は Sora に対して HTTP 経由で実行できます。

## 用語

- object- `JSON Object` です
  - [HTTPie](https://httpie.io/) では `key:='{"spam": "egg"}'` のように指定してください

## API の種類

### API

正式リリースされている API

### 実験的 API

仕様が確定していない API

詳細は [実験的 API](EXPERIMENTAL_API.html) をご確認ください。

### 非推奨 API

期限が来たら廃止される API

詳細は [非推奨 API](DEPRECATED_API.html) をご確認ください。

### 廃止 API

廃止された API

詳細は [廃止 API](OBSOLETE_API.html) をご確認ください。

### テスト API

テストで利用する API

詳細は [テスト API](TEST_API.html) をご確認ください。

## x-sora-target ヘッダー

API は [DynamoDB や Route53 などの AWS API が独特な仕様なので紹介](https://gist.github.com/voluntas/811240c5b6a169ae1c6ac401e0197417) を参考にしており、 `x-sora-target` というヘッダーを使って実行します。

- すべての API は POST を使用します
- すべての API の PATH は `/` です
- リクエストの Body には JSON を使用します
- レスポンスの Body には JSON を使用します

## 設定

### api_port

API のポート番号を変更したい場合は `sora.conf` の [api_port](SORA_CONF.html#4adab7) にて、 API のポート番号を設定してください。

デフォルトでは 3000 番を利用します。

```ini
api_port = 3000
```

### api_loopback_address_only

API へのアクセスをループバックアドレスからのみに制限します。
本番環境では可能な限り有効にしてください。

```ini
api_loopback_address_only = true
```

### api_cors_origin

> **警告**
>
> 本番環境ではこの設定は有効にしないでください。

API をクロスドメインで使用したい場合に設定します。

```ini
api_cors_origin = http://127.0.0.1:5000
```

こうすることで、ブラウザで `http://127.0.0.1:5000` から API を叩くことができるようになります。

## HTTPie

ここでの例では HTTPie という Python のライブラリを使用しています。

[🥧 HTTPie for Terminal — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more.](https://github.com/httpie/httpie)

### インストール

- Ubuntu は `apt install httpie` で入ります
- CentOS は `yum install httpie` で入ります
- macOS は `brew install httpie` または `port install httpie` で入ります

詳細は  をご確認下さい。