###
API
###

概要
====

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

用語
====

- object

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

API の種類
==========

API
----------

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

実験的 API
----------------

仕様が確定していない API

詳細は :doc:`実験的 API </EXPERIMENTAL_API>` をご確認ください。

非推奨 API
--------------

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

詳細は :doc:`非推奨 API </DEPRECATED_API>` をご確認ください。

廃止 API
---------

廃止された API

詳細は :doc:`廃止 API </OBSOLETE_API>` をご確認ください。

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`` の :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. <https://github.com/httpie/httpie>`_

.. note:: 時雨堂は HTTPie 作者のスポンサーです

インストール
------------

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

詳細は https://httpie.io/docs/cli/installation をご確認下さい。