1 APIs
Fabio Manganiello edited this page 2024-05-25 23:19:28 +02:00
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

APIs

HTTP API

Actions and procedures can also be called using the JSON-RPC API exposed by Platypush.

Your configuration requires the backend.http section enabled if you want to use the HTTP API - default listen port: 8008.

After ensuring that the HTTP backend is enabled, head to http://localhost:8008 and register a new user.

Platypush local user registration
page

From the Web UI, head to SettingsTokens, insert your password again and click Generate JWT token.

User token generation UI

Alternatively, you can retrieve a token via HTTP request:

 curl -XPOST -H 'Content-Type: application/json' -d '
{
  "username": "$YOUR_USER",
  "password": "$YOUR_PASSWORD"
}' http://localhost:8008/auth

You can then send requests to Platypush using a simple RPC API:

 curl -XPOST \
    -d '{"type":"request", "action":"procedure.at_home"}' \
    -H "Authorization: Bearer $YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    http://localhost:8008/execute

{
  "id": "724754df98968247a284557ce32f74bb",
  "type": "response",
  "target": "http",
  "origin": "myhost",
  "_timestamp": 1716575901.046127,
  "response": {
    "output": {
      "success": true
    },
    "errors": []
  }
}

If your procedure returned something, then that will be returned on the API response too, so downstream consumers can use it.

The POST /execute endpoint accepts a payload in the format:

{
  "type": "request",  // Constant
  "action": "<plugin-name>.<action-name>",  // Or procedure.<name>
  "args": {
    "arg1": "arg2",
    // ...
  }
}

In our procedure.at_home example, you can for instance create an automation snippet paired with your phone that runs the routine whenever you arrive home (or your phone does):

  1. Install an app like Tasker to create automation tasks on your Android device.

  2. Install a plugin like AutoLocation to create automation tasks based on your phone's location.

  3. Create a profile that triggers whenever you enter your home location (and/or exit it).

Tasker screenshot showing an At Home/Outside Home pair of
profiles

  1. Leverage the HTTP Request Tasker action to send a request to your Platypush API to trigger the routine.

The Execute tab

The Web interface also provides an Execute tab under the menu sidebar. You can use this tab to dynamically discover the actions exposed by various plugins (and also your own procedures):

Screenshot of the Execute tab showing the autocomplete discovery of the
actions

Screenshot of the Execute tab showing the automatically generated
documentation for a given action and its
parameters

Screenshot of the Execute tab showing the output of an action being
run

Websocket API

Events

You can subscribe to events generated by the application over the /ws/events Websocket endpoint, and send events to this endpoint too.

This is useful if you want to synchronize Platypush events with another client, or send custom events outside of those native to the application and build custom automation hooks on them.

Sending events:

 wscat -H "Authorization: Bearer $YOUR_TOKEN" \
    -c "ws://localhost:8008/ws/events" \
    -w 1 \
    -x '
{
  "type": "event",
  "args": {
    "type": "platypush.message.event.custom.CustomEvent",
    "subtype": "foo",
    "args": {
      "bar": "baz"
    }
  }
}'

Receiving events:

 wscat -H "Authorization: Bearer $YOUR_TOKEN" -c "ws://localhost:8008/ws/events"

Actions

You can also send requests to the /ws/requests Websocket endpoint, and get responses asynchronously on the same channel:

 wscat -H "Authorization: Bearer $YOUR_TOKEN" \
    -c "ws://localhost:8008/ws/requests" \
    -w 1 \
    -x '{"type": "requests", "action": "procedure.foo.bar"}'

Web hooks

You can use Platypush to expose your custom routines as dynamic Web hooks that can be called by any client.

All you need is to register a listener for a WebhookEvent

from platypush import run, when
from platypush.events.http.hook import WebhookEvent

hook_token = "abcdefabcdef"

# Expose the hook under the /hook/at_home endpoint
@when(WebhookEvent, hook="at_home")
def at_home_webhook(event: WebhookEvent):
    # Unlike the calls to /execute, custom web hooks are unauthenticated.
    # If you want authentication, you'll need to implement your custom logic by
    # parsing the event headers
    if event.headers.get("X-Token") != hook_token:
        # Tuple with <response, http-code, [response-headers]>
        event.send_response(("Unauthorized", 401))
        return

    run('procedure.at_home')

    # Return anything back to the client
    return {'status': 'ok'}

Then you can invoke your custom logic over HTTP:

 curl -H 'X-Token: abcdefabcdef' 'http://localhost:8008/hook/at_home'

Platypush as a library

You can also use Platypush as a library in your own scripts.

For example, you may want to run a bunch of scripts that control your lights outside of Platypush, but use a Platypush configuration file as your script configuration, and use a plugin as the API for your controller:

from platypush import run
from platypush.config import Config

# Optional. Defaults to the default config.yaml if missing
Config.init('/path/to/my/config.yaml')

# ...

run('light.hue.toggle', groups=['Living Room', 'Hall'])

# ...