Apps Endpoints - fullphat/snarl_network_protocol GitHub Wiki

Overview

These endpoints allow applications register and unregister themselves.

Contents

• GET /apps: Returns all registered applications
• GET /apps/{Guid}: Returns details for a particular application
• POST /apps: Registers (or updates) an application
• DELETE /apps/{AppId}: Unregisters an application

Usage

GET endpoints do not require authentication, and use the application's Guid as the resource identifier. You can find the application's Guid by calling GET /apps.

POST and DELETE endpoints require the application's password (if one was specified during registration) to be included in the request oxide-password header. These methods also require the application's identifier - as opposed to its Guid - to be used as the resource identifier.

Endpoints

GET /apps

GET /apps/{Guid}

Returns details for all registered applications, or just for the application specified by {Guid}. The root endpoint will return a list of RegistrationInfo objects; the resource-specific version will return a single RegistrationInfo object for the specified registration.

Authentication

Not required.

Request Body

Not required.

Response

UPDATE REQUIRED

Code	Likely cause
OK	Specified events were added or updated successfully.
400	Incorrectly formatted data or at least one event object missing an event-id parameter
401	Transport authentication or application password protection mismatch
NotFound	The application specified in AppId isn't registered

Notes

• Unlike other endpoints, this endpoint uses the application's Guid, not it's identifier.

Example

Request

GET /v2/apps/fb4d1dd0-d628-4c42-97d5-9baa45fc77a0

Response

{
  "Meta": {
    "Code": 200,
    "Text": "OK",
    "Message": "",
    "Timestamp": "2018-05-02T13:28:47.7295473+01:00",
    "Host": "cs30",
    "Platform": "Win32NT",
    "PlatformVersion": "6.1.7601.65536"
  },
  "Data": {
    "Guid": "fb4d1dd0-d628-4c42-97d5-9baa45fc77a0",
    "Title": "AudioBlart",
    "Type": "Extension",
    "FirstRegistered": "2017-05-28T08:56:49",
    "LastRegistered": "2018-05-02T11:54:47.371846+01:00",
    "Events": [
      {
        "Guid": "d15baeb8-fdf1-4bf5-b310-d7b3b41b9d2d",
        "Name": "(Default)",
        "Enabled": true
      },
      {
        "Guid": "1b590054-08f9-4e80-b2de-22b820d6ea87",
        "Name": "Speaker is muted or unmuted",
        "Enabled": true
      },
      {
        "Guid": "ab7729fe-e81c-4baf-b893-eac0bb485d93",
        "Name": "Volume changed",
        "Enabled": true
      }
    ],
    "Icons": {
      "file": "Q:\\audioblart.png"
    },
    "Rules": []
  }
}

---

POST /apps

Registers an application.

Authentication

Recommended, although not mandatory. If the application has already been registered, and a password was supplied at the time, the same password must be included in the oxide-password header of the request.

Request Body

A RegistrationContent object with at least the AppId and Title fields completed.

Response

UPDATE REQUIRED

Code	Likely cause
OK	Specified events were added or updated successfully.
400	Incorrectly formatted data or at least one event object missing an event-id parameter
401	Transport authentication or application password protection mismatch
NotFound	The application specified in AppId isn't registered

Notes

Example

Request

POST /v2/apps

Body

{
  "AppId": "foo",
  "title": "App Foo",
  "icon": "!misc-chair",
  "description": "This is application Foo",
  "Version": "6.1.2.3.foo",
}

Response

{
  "Meta": {
    "Code": 200,
    "Text": "OK",
    "Message": "",
    "Timestamp": "2018-05-02T11:56:23.9073312+01:00",
    "Host": "cs30",
    "Platform": "Win32NT",
    "PlatformVersion": "6.1.7601.65536"
  },
  "Data": {
    "Guid": "c6ce3fcd-043c-4e56-bebe-c407ae0b2bd1"
  }
}

---

DELETE /apps/{AppId}

Unregisters the specified application.

Authentication

If a password was specified when the application was first registered, the same password must be included in the oxide-password header.

Request Body

Not required.

Response

UPDATE REQUIRED

Code	Likely cause
OK	Specified events were added or updated successfully.
400	Incorrectly formatted data or at least one event object missing an event-id parameter
401	Transport authentication or application password protection mismatch
NotFound	The application specified in AppId isn't registered

Notes

Example

Request

DELETE /v2/apps/foo

Response

{
  "Meta": {
    "Code": 200,
    "Text": "OK",
    "Message": "",
    "Timestamp": "2018-05-02T13:31:58.9020478+01:00",
    "Host": "cs30",
    "Platform": "Win32NT",
    "PlatformVersion": "6.1.7601.65536"
  },
  "Data": null
}