# `netapi` modules

## Introduction to netapi modules

netapi modules provide API-centric access to Salt. Usually externally-facing services such as REST or WebSockets, XMPP, XMLRPC, etc.

In general netapi modules bind to a port and start a service. They are purposefully open-ended. A single module can be configured to run as well as multiple modules simultaneously.

netapi modules are enabled by adding configuration to your Salt Master config file and then starting the salt-api daemon. Check the docs for each module to see external requirements and configuration settings.

Communication with Salt and Salt satellite projects is done using Salt's own Python API. A list of available client interfaces is below.

salt-api

Prior to Salt's 2014.7.0 release, netapi modules lived in the separate sister projected `salt-api`. That project has been merged into the main Salt project.

See also

The full list of netapi modules

## Client interfaces

Salt's client interfaces expose executing functions by crafting a dictionary of values that are mapped to function arguments. This allows calling functions simply by creating a data structure. (And this is exactly how much of Salt's own internals work!)

class salt.netapi.NetapiClient(opts)

  Provide a uniform method of accessing the various client interfaces in Salt in the form of low-data data structures. For example:

      >>> client = NetapiClient(__opts__)
      >>> lowstate = {'client': 'local', 'tgt': '*', 'fun': 'test.ping', 'arg': ''}
      >>> client.run(lowstate)

  local(*args, **kwargs)

    Run execution modules synchronously

    See `salt.client.LocalClient.cmd()` for all available parameters.

    Sends a command from the master to the targeted minions. This is the same interface that Salt's own CLI uses. Note the `arg` and `kwarg` parameters are sent down to the minion(s) and the given function, `fun`, is called with those parameters.

    Returns:

      Returns the result from the execution module

  local_async(*args, **kwargs)

    Run execution modules asynchronously

    Wraps `salt.client.LocalClient.run_job()`.

    Returns:

      job ID

  local_subset(*args, **kwargs)

    Run execution modules against subsets of minions

    New in version 2016.3.0.

    Wraps `salt.client.LocalClient.cmd_subset()`

  runner(fun, timeout=None, full_return=False, **kwargs)

    Run runner modules <all-salt.runners> synchronously

    Wraps `salt.runner.RunnerClient.cmd_sync()`.

    Note that runner functions must be called using keyword arguments. Positional arguments are not supported.

    Returns:

      Returns the result from the runner module

  runner_async(fun, **kwargs)

    Run runner modules <all-salt.runners> asynchronously

    Wraps `salt.runner.RunnerClient.cmd_async()`.

    Note that runner functions must be called using keyword arguments. Positional arguments are not supported.

    Returns:

      event data and a job ID for the executed function.

  ssh(*args, **kwargs)

    Run salt-ssh commands synchronously

    Wraps `salt.client.ssh.client.SSHClient.cmd_sync()`.

    Returns:

      Returns the result from the salt-ssh command

  wheel(fun, **kwargs)

    Run wheel modules synchronously

    Wraps `salt.wheel.WheelClient.master_call()`.

    Note that wheel functions must be called using keyword arguments. Positional arguments are not supported.

    Returns:

      Returns the result from the wheel module

  wheel_async(fun, **kwargs)

    Run wheel modules asynchronously

    Wraps `salt.wheel.WheelClient.master_call()`.

    Note that wheel functions must be called using keyword arguments. Positional arguments are not supported.

    Returns:

      Returns the result from the wheel module

- HTTP Modules
  - The `salt.utils.http` Library
    - Configuring Libraries
    - `salt.utils.http.query()`
      - HTTPS Request Methods
      - Data Formatting and Templating
      - Headers
      - Authentication
      - Cookies and Sessions
      - Proxy
    - Return Data
    - Writing Return Data to Files
    - SSL Verification
    - CA Bundles
      - Updating CA Bundles
    - Test Mode
  - Execution Module
  - Runner Module
  - State Module
- Writing netapi modules
  - Configuration
  - The `__virtual__` function
  - The `start` function
  - Multiple instances
  - Inline documentation
  - Loader “magic” methods