クライアントからこのAPIをコールする方法が2通りあります:

• 1つ目の方法は、次のように/apiに対してPOSTメソッドを実行することです。このメソッドのcmd_functionパラメータには関数名を格納し、それ以外のすべてのパラメータには引数を格納します。例えば、cmd_function=vector_length&x=1&y=2&z=3です。

  requestsライブラリを使用したPythonクライアントコード

  import requests
  
  resp = requests.post("http://127.0.0.1:8008/api", {
      "cmd_function": "geo.vector_length",
      "x": "1", "y": "2", "z": "3"    
  })
  print(resp.text)
  

  この手法なら、クライアントの実装は簡単ですが、ハンドラーがすべての引数値を文字列として受信するので、ハンドラーにて型のチェック/変換をするコードをさらに追加するか、または、関数デコレータでarg_types辞書を指定する必要があります(上記参照)。

  Note

  型変換を追加しなかった場合、このサンプルは動作しないです。 型変換を用意したサンプルは、以下のデフォルト値と引数型を参照してください。

• 推奨する2つ目の方法は、次のように/apiに対してPOSTメソッドを実行することです。このメソッドのjsonパラメータには、関数名の文字列、位置指定引数のリスト、キーワード引数が定義されたオブジェクトを含んだJSONオブジェクトの文字列エンコードを格納します。例えば、["geo.vector_length", (1, 2, 3), {}]です。

  この手法なら、型情報が暗黙的にエンコードされ、もっと複雑な引数型を格納することができます。

  追加のmultipart/form-data引数は、キーワード引数を追加で格納さるものと解釈されます。 この引数を使用することで、base64エンコードする必要なくバイナリデータを渡すことができます(jsonという名前のバイナリデータ引数を持つことはできません)。 webapiclient.pyを使用したPythonクライアントは、この詳細について気にする必要はありません。

  requestsライブラリを使用したPythonの最小限のクライアントコード

  import json
  import requests
  
  def call_api(endpoint_url, function_name, *args, **kwargs):
      return requests.post(endpoint_url,
          data={"json": json.dumps([function_name, args, kwargs])}).json()
  })
  

  Houdiniに同梱されているwebapiclient.pyモジュールは、API関数をコール可能な完全なPythonクライアントを実装しています。 このモジュールは、Houdiniに依存しておらず、あなた自身のプロジェクトにコピーすることができます。 このモジュールを使用すれば、もっと自然な構文を使用してAPI関数をコールすることができます。

  service = webapiclient.Service("http://127.0.0.1:8008/api")
  print(service.geo.vector_length(1, 2, 3))
  

  JavaScriptの最小限のクライアントコード

  function call_api(function_name, kwargs)
  {
      var formdata = new FormData();
      formdata.append("json", JSON.stringify(
          [function_name, [], kwargs]));
  
      return fetch("/api", {
          method: "POST",
          body: formdata
      });
  }
  

  バイナリデータを扱う完全なJavaScriptクライアントが以下に用意されています。

• API関数にはデフォルト値を持たせることができ、コール側は、JSONエンコードの[name, args, kwargs]コールの手法を使用した場合には、位置指定引数とキーワード引数を混在させて使用することができます。

  デフォルト値を使用したサーバーとPythonクライアントのサンプル。

  # サーバーコード:
  @hou.webServer.apiFunction("test")
  def foo(a, b=2, c=3):
      return (a, b, c)
  
  
  # クライアントコード:
  service = webapiclient.Service("http://127.0.0.1:8008/api")
  
  # 以下のコールはどれも同じで[1, 2, 3]を返します:
  service.test(1, 2, 3)
  service.test(1, 2, c=3)
  service.test(a=1, c=3, b=2)
  

• URLエンコードでコールする手法を使用した場合、すべての引数が文字列として渡されますが、API関数を宣言する時に型を指定することが可能です。

  Python2とPython3で引数型を指定する

  @hou.webServer.apiFunction("test", arg_types={"value": int})
  def double_int(value):
      return value * 2
  
  # "value=3"を含んだPOSTボディを使ってコールすると、その文字列の"3"は整数の3に変換されます。
  

  Python3では、型のヒントと一緒に引数型を指定することもできます。

  @hou.webServer.apiFunction("test")
  def double_int(value: int):
      return value * 2
  

• API関数は、bytearrayオブジェクト(Python3だとbytesオブジェクト)を返すことで、または、Content-Typeがapplication/octet-streamのレスポンスを返すことで、 または、hou.webServer.fileResponse()を使用してapplication/octet-streamを利用するファイルの内容をストリーム化することで、 または、関数の戻り値がバイナリであることをマークしてbytesを返すことで、バイナリデータを返すことができます。

• webapiclient.pyがバイナリデータの戻り値を受信すると、それをすべてメモリにロードする必要がないようにクライアント側でストリーム化する機会が得られるファイルライクなオブジェクトを返します。 クライアント側ですべてのデータを読み込まない場合に要求が閉じられるようにするために、クライアント側でその結果に対してwithステートメントを使用してください。

  バイナリデータを返すサーバーとそれを受信するPythonクライアント

  # サーバーは、以下のようにバイナリデータを返すことができます:
  
  @hou.webServer.apiFunction("test")
  def binary_data(request):
      return bytearray([0, 0, 65, 66, 0])
  
  
  # クライアントは、他の関数と同様に関数をコールすることができ、アンパックされたJSONの代わりに`bytes`オブジェクトを受信します:
  
  with service.test.binary_data() as result_stream:
      binary_data = result_stream.read()
  

  API関数の戻り値がバイナリであることをマークしたサーバー

  @hou.webServer.apiFunction("test", return_binary=True)
  def binary_data(request):
      return b'\x00\x00AB\x00'
  

• webapiclient.pyを使用した場合、クライアントは、bytearrayを使用してバイナリデータを引数に渡すことができたり、webapiclient.Fileオブジェクトを使用してディスク上のファイルからバイナリデータをストリーム化することができます。 バイナリデータの引数は必ずキーワード引数を使用して渡す必要があり、位置指定引数で渡すことはできないことに注意してください。

  バイナリデータを送信するPythonクライアントとそれを受信するサーバー

  # クライアントは、以下のようにバイナリデータを送信することができます:
  service.test.use_binary_data(
      small_data=bytearray([0, 0, 65, 66, 0]),
      big_data=webapiclient.File("/path/to/binary/file"))
  
  
  # サーバーは、バイナリデータを[Hom:hou.webServer#UploadedFile]オブジェクトとして受信し、
  # そのオブジェクトからバイナリデータを読み込むことができます:
  import shutil
  
  @hou.webServer.apiFunction("test")
  def use_binary_data(request, small_data, big_data):
      small_data_as_bytes = small_data.read()
      with open("uploaded_file.bin", "wb") as open_file:
          shutil.copyfileobj(big_data, open_file)
  

• 422ステータスを返すには、API関数からhou.webServer.APIErrorを引き起こします。

• webapiclient.pyを使用した場合、200以外のステータスコードを持ったどのレスポンスも、クライアントに対してwebapiclient.APIError例外を引き起こします。

• API関数がAPIError以外の例外を生成した場合、サーバーは500ステータスコードを返します。 サーバーがデバッグモードの場合、そのレスポンスにはスタックトレースが含まれます。

  エラーを説明したサーバーコードとPythonクライアントコード

  # サーバー:
  
  @hou.webServer.apiFunction("test")
  def illustrate_errors(request, value):
      if value == 0:
          return ["successful", "result"]
      if value == 1:
          raise hou.webServer.APIError("an error occurred")
      if value == 2:
          raise hou.webServer.APIError({"any": "json-encodable"})
      if value == 3:
          raise hou.OperationFailed("an unhandled exception")
  
  
  # クライアント:
  
  print(service.test.illustrate_errors(0)) # ["successful", "result"]がプリントされます。
  
  try:
      service.test.illustrate_errors(1)
  except webapiclient.APIError as e:
      print(str(e)) # "an error ocurred"がプリントされます。
      print(e.status_code) # 422がプリントされます。
  
  try:
      service.test.illustrate_errors(2)
  except webapiclient.APIError as e:
      print(e.args[0]["any"]) # "json-encodable"がプリントされます。
      print(e.status_code) # 422がプリントされます。
  
  try:
      service.test.illustrate_errors(3)
  except webapiclient.APIError as e:
      print(e.status_code) # 500がプリントされます。
  

以下の情報は、新しい言語でクライアントを実装する時に役立ちます。 参考にwebapiclient.pyを参照してください。

• testというネームスペース内でaとbの引数を受け取るfunc1関数をコールすると仮定します。 aの値には、位置指定引数で1を渡し、bの値には、キーワード引数で“two”を渡します。

  • JSONエンコードの["test1.func", [1], {"b": "two"}]は'["test.func1", [1], {"b": "two"}]'となります。

  • そのJSONエンコードの値をjsonという名前でURLエンコードすると次のようになります: json=%5B%22test.func1%22%2C+%5B1%5D%2C+%7B%22b%22%3A+%22two%22%7D%5D

  • これをサーバーの/apiURLパスにPOSTします。

• POSTは推奨されるリクエストメソッドですが、他のメソッドも技術的に対応しています。 HTTPは結果をキャッシュ可能なものとして定義するので、副作用を持つ関数または引数以外のデータに依存する関数に対してGETを使用しないでください。

• URIエンコーディングとmultipart/form-dataエンコーディングのどちらにも対応しています。

• バイナリ引数を送信したり、または、大量の引数をストリーム化したいのであれば、 JSONエンコードされたデータにそれらの引数を含めないでください。 代わりに、それらの引数をmultipart/form-dataとしてボディ内にエンコードしてその引数名を使用し、Content-Typeにapplication/octet-streamを使用してください。 jsonという名前のバイナリ引数は対応していません。

• サーバーがエラーメッセージをJSONとして返せるようにするために"application/json, */*"のAcceptヘッダを送信してください。

• サーバーがapplication/octet-streamのContent-Typeを返す場合、API関数からのレスポンスはバイナリデータであってJSONではありません。

• サーバーは、成功すれば200、APIError例外を引き起こせば422、制御されていない例外があれば500でレスポンスを返します。

• API関数はリクエストに対してフルアクセスすることができるので、ヘッダを調べることができます。 この能力は、認証を実装する時に役立ちます。

• API関数からのレスポンスを、HTTPステータスコード、Content-Type、追加ヘッダと一緒に返すことができます。 ただし、このプロトコルに準拠し、認証以外の独自の挙動を追加しないように心がけてください。