###
API
###
概要
====
API は Sora に対して HTTP 経由で実行できます。
用語
====
- object
- ``JSON Object`` です
- `HTTPie `_ では ``key:='{"spam": "egg"}'`` のように指定してください
API の種類
==========
API
----------
正式リリースされている API
実験的 API
----------------
仕様が確定していない API
詳細は :doc:`実験的 API ` をご確認ください。
非推奨 API
--------------
期限が来たら廃止される API
詳細は :doc:`非推奨 API ` をご確認ください。
廃止 API
---------
廃止された API
詳細は :doc:`廃止 API ` をご確認ください。
x-sora-target ヘッダー
======================
API は `DynamoDB や Route53 などの AWS API が独特な仕様なので紹介 `_ を参考にしており、 ``x-sora-target`` というヘッダーを使って実行します。
- すべての API は POST を使用します
- すべての API の PATH は ``/`` です
- リクエストの Body には JSON を使用します
- レスポンスの Body には JSON を使用します
設定
====
api_port
--------
API のポート番号を変更したい場合は ``sora.conf`` の :ref:`api_port` にて、 API のポート番号を設定してください。
デフォルトでは 3000 番を利用します。
.. code-block:: ini
api_port = 3000
api_loopback_address_only
-------------------------
API へのアクセスをループバックアドレスからのみに制限します。
本番環境では可能な限り有効にしてください。
.. code-block:: ini
api_loopback_address_only = true
api_cors_origin
---------------
.. warning:: 本番環境ではこの設定は有効にしないでください。
API をクロスドメインで使用したい場合に設定します。
.. code-block:: 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. `_
.. note:: 時雨堂は HTTPie 作者のスポンサーです
インストール
------------
- Ubuntu は ``apt install httpie`` で入ります
- CentOS は ``yum install httpie`` で入ります
- macOS は ``brew install httpie`` または ``port install httpie`` で入ります
詳細は https://httpie.io/docs/cli/installation をご確認下さい。