There are two ways to call the API from a client:

• The way first is to POST to /api, where the cmd_function parameter contains the function name, and all other parameters contain arguments. For example, cmd_function=vector_length&x=1&y=2&z=3.

  Python client code using the requests library

  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)
  

  This approach is simpler to implement a client for, but the handler receives all argument values as strings so you must either add extra type checking/conversion code in your handler or specify an arg_types dict in the function decorator (see above).

  Note

  Without extra type conversions, this example will not work. See Default values and argument types below for an example of providing type conversions.

• The second and recommended way is POST to /api, where the json parameter contains a string encoding of a JSON object containing the function name string, a list of positional arguments, and the an object containing keyword arguments. For example, ["geo.vector_length", (1, 2, 3), {}].

  This approach implicitly encodes type information and allows for more complex argument types.

  Any additional multipart/form-data arguments are interpreted to contain additional keyword arguments. Use these arguments to pass binary data instead of having to base64-encode it. (You cannot have a binary data argument named json.) Python clients using webapiclient.py do not need to be aware of this detail.

  Python minimal client code using the requests library

  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()
  })
  

  The webapiclient.py module that ships with Houdini implements a complete Python client that can call API functions. It does not depend on Houdini and can by copied into your own projects. With it you can call API functions using a more natural syntax.

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

  JavaScript minimal client code

  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
      });
  }
  

  A full JavaScript client that handles binary data is provided below.

• API functions may have default values, and the caller can use a mix of positional and keyword arguments when using the JSON-encoded [name, args, kwargs] calling approach.

  Server and Python client example using default values.

  # Server code:
  @hwebserver.apiFunction("test")
  def foo(a, b=2, c=3):
      return (a, b, c)
  
  
  # Client code:
  service = webapiclient.Service("http://127.0.0.1:8008/api")
  
  # These calls are all equivalent and return [1, 2, 3]:
  service.test(1, 2, 3)
  service.test(1, 2, c=3)
  service.test(a=1, c=3, b=2)
  

• Using the url-encoded calling approach will pass all arguments as strings, but it is possible to specify types when declaring the API function.

  Specifying argument types in Python 2 and 3

  @hwebserver.apiFunction("test", arg_types={"value": int})
  def double_int(value):
      return value * 2
  
  # Calling with a POST body of "value=3" will convert the string "3"
  # to the integer 3.
  

  In Python 3, argument types can also be specified with type hints.

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

• API functions can return binary data by returning a bytearray object (or bytes in Python 3), returning a response with a Content-Type of application/octet-stream, using a hwebserver.fileResponse to stream the contents of a file using application/octet-stream, or marking the function as returning binary and returning bytes.

• When webapiclient.py receives a binary data return value, it will return a file-like object to give the client the opportunity to stream it instead of having to load it all into memory. The client should use the with statement on the result to ensure the request is closed in case the client does not read all the data.

  Server returning binary data and Python client receiving it

  # The server can return binary data as follows:
  
  @hwebserver.apiFunction("test")
  def binary_data(request):
      return bytearray([0, 0, 65, 66, 0])
  
  
  # The client can call the function like any other and receives a
  # `bytes` object instead of unpacked JSON:
  
  with service.test.binary_data() as result_stream:
      binary_data = result_stream.read()
  

  Server marking an API function as returning binary

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

• Using webapiclient.py, the client can pass binary data in arguments using bytearray objects or stream it from a file on disk using webapiclient.File objects. Note that binary data arguments must be passed using keyword arguments and cannot be passed positionally.

  Python client sending binary data and server that receives it

  # The client can send binary data as follows:
  service.test.use_binary_data(
      small_data=bytearray([0, 0, 65, 66, 0]),
      big_data=webapiclient.File("/path/to/binary/file"))
  
  
  # The server receives the binary data as UploadedFile
  # objects that it can read from:
  import shutil
  import hwebserver
  
  @hwebserver.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)
  

• Raise a hwebserver.APIError from an API function to return a 422 status.

• When using webapiclient.py, any responses with a non-200 status code will raise a webapiclient.APIError exception to the client.

• If your API function generates an exception other than an APIError, the server will return a 500 status code. If the server is in debug mode the response contains a stack trace.

  Server and Python client code illustrating errors

  # The server:
  
  @hwebserver.apiFunction("test")
  def illustrate_errors(request, value):
      if value == 0:
          return ["successful", "result"]
      if value == 1:
          raise hwebserver.APIError("an error occurred")
      if value == 2:
          raise hwebserver.APIError({"any": "json-encodable"})
      if value == 3:
          raise hwebserver.OperationFailed("an unhandled exception")
  
  
  # The client:
  
  print(service.test.illustrate_errors(0)) # prints ["successful", "result"]
  
  try:
      service.test.illustrate_errors(1)
  except webapiclient.APIError as e:
      print(str(e)) # prints "an error ocurred"
      print(e.status_code) # prints 422
  
  try:
      service.test.illustrate_errors(2)
  except webapiclient.APIError as e:
      print(e.args[0]["any"]) # prints "json-encodable"
      print(e.status_code) # prints 422
  
  try:
      service.test.illustrate_errors(3)
  except webapiclient.APIError as e:
      print(e.status_code) # prints 500
  

The following information is helpful when implementing a client in a new language. See webapiclient.py as a reference.

• Suppose you're calling the function func1 in the namespace test which takes arguments a and b. You're passing 1 for the value of a by position and “two” for the value of b by keyword argument.

  • JSON-encode ["test1.func", [1], {"b": "two"}] to get '["test.func1", [1], {"b": "two"}]'

  • URL-encode the JSON-encoded value with the name json: json=%5B%22test.func1%22%2C+%5B1%5D%2C+%7B%22b%22%3A+%22two%22%7D%5D

  • POST this to the server’s /api URL path.

• POST is the recommended request method, though anything is technically supported. Don’t use GET for functions that have side effects or rely on data other than arguments, since HTTP defines the results as cacheable.

• URI-encoding and multipart/form-data encodings are both supported.

• To send binary arguments, or otherwise stream large arguments, do not include them in the JSON-encoded data. Instead, encode them as multipart/form-data them in the body, using the argument name, and use a Content-Type of application/octet-stream. Binary arguments named json are not supported.

• Send an Accept header of "application/json, */*" to have the server return error messages as JSON.

• If the server returns a Content-Type of application/octet-stream then the response back from the API function is binary data and not JSON.

• The server will respond with 200 on success, 422 if the server raised an APIError exception, and 500 if the server had an unhandled exception.

• API functions have full access to the request so they can look at headers. This ability is helpful when implementing authentication.

• You can return any response from an API function, with any HTTP status code, and content type, and any additional headers. You are encouraged to confirm to this protocol, though, and not add custom behavior other than authentication.