Mutator HTTP API

The Mutator HTTP API is an API you can implement to expose mutators and receive mutation events.

You can make Deviant aware of a given mutator server's HTTP API by either hosting the server as a modality-reflector (opens new window) mutator plugin or by explicitly pointing a modality-reflector instance at an already-running mutator server's URL.

# As A Plugin

To run a mutator server as a modality-reflector plugin, place the executable program file for the server into a modality-reflector-plugins/mutators directory relative to the current working directory.

Then, run in a terminal:

modality-reflector run --mutator your-mutator-server-binary-file-name

This will produce an indefinitely-running modality-reflector process that will start up the mutator server executable and pass it a MODALITY_REFLECTOR_CONFIG environment variable describing the filesystem path to a configuration file.

The plugin configuration format is in TOML, and the mutation.mutator-http-api-port field will be set to the expected port where the modality-reflector will expect to find the HTTP API available after the mutator server starts up.

The MODALITY_AUTH_TOKEN environment variable will also be set.

# As An External Server

If your mutator server providing the HTTP API is operationally set up such that it should not be tied strictly to the lifecycle of a modality-reflector process, you can loosely couple the two processes instead.

In your modality-reflector configuration file, edit it such that the mutation table's external-mutator-urls field contains the expected URL for the HTTP API.

[mutation]
external-mutator-urls = ["http://wherever.com:9123/your/server/route"]

Then, run in a terminal:

modality-reflector run --config path/to/your/modality-reflector/config.toml

# Authentication

Authentication may be optionally required to use these APIs.

If required, authentication is provided using the mutator_apikey HTTP header.

# Endpoints

This is the set of end points a mutator must implement.

# list mutators

GET /mutator

List all mutators.

Returns a list of all current mutators.

The modality reflector will periodically poll this endpoint to query what mutators this server exposes.

# Responses

Status Meaning Description Schema
200 OK (opens new window) List mutators successfully Mutator
400 Bad Request (opens new window) Missing mutator_apikey request header None
401 Unauthorized (opens new window) Unauthorized to view mutators None

# Example Responses

200 Response
[
  {
    "attributes": {
      "mutator.name": "message bus delayer",
      "mutator.layer": "operational",
      "mutator.mycorp.deployment.pod.id": 45926
    },
    "mutator_correlation_id": "abc123"
  }
]

# create mutation

POST /mutator/{mutator_correlation_id}/mutation

Create new mutation for a mutator.

Instructs your mutator server to create a new mutation for a mutator, overriding its state in the system.

# Request Body

{
  "mutation": "02d72373-2535-4f80-ba4c-b4337d54f8eb",
  "params": {
    "set_to_value": 40,
    "degrees": "celsius"
  }
}

# Parameters

Name In Type Required Description
mutator_correlation_id path string true Mutator's server-local correlation id
body body Mutation true

# Responses

Status Meaning Description Type
201 Created (opens new window) Mutation created successfully None
400 Bad Request (opens new window) Missing mutator_apikey request header None
401 Unauthorized (opens new window) Unauthorized to create mutations None
404 Not Found (opens new window) Target mutator not found None
500 Internal Server Error (opens new window) Internal mutator error None

# delete mutations

DELETE /mutator/{mutator_correlation_id}/mutation

Delete / reset all mutations for a mutator

Instructs your mutator to delete all mutations, resetting its state in the system.

# Parameters

Name In Type Required Description
mutator_correlation_id path string true Mutator's server-local correlation id

# Responses

Status Meaning Description Type
200 OK (opens new window) Mutations reset / deleted successfully None
400 Bad Request (opens new window) Missing mutator_apikey request header None
401 Unauthorized (opens new window) Unauthorized to delete mutations None
404 Not Found (opens new window) Target mutator not found None

# Schemas

# AttrKey

"string"

# Properties

Name Type Required Restrictions Description
anonymous string false none none

# AttrVal

{
  "TimelineId": "7bcbf99b-df5f-465b-9da9-8024903a95eb"
}

# Properties

oneOf:

Named types are represented as an object, standard JSON types are simply their native representation.

# BigInt

0

An integer that requires more than 64 bits to represent its value.

# Properties

Name Type Required Restrictions Description
anonymous integer false none none

# EventCoordinate

{
  "id": 0,
  "timeline_id": "8d0dde4e-7b83-4f50-8c64-edd64e5d1e76"
}

# Properties

Name Type Required Restrictions Description
id integer(int32) true none none
timeline_id TimelineId true none none

# LogicalTime

0

# Properties

Name Type Required Restrictions Description
anonymous integer(int64) false none none

# Mutation

{
  "mutation": "02d72373-2535-4f80-ba4c-b4337d54f8eb",
  "params": {
    "set_to_value": 40,
    "degrees": "celsius"
  }
}

# Properties

Name Type Required Restrictions Description
mutation string(uuid) true none none
params object true none Mutation parameters

# Mutator

{
  "attributes": {
    "mutator.name": "message bus delayer",
    "mutator.layer": "operational",
    "mutator.mycorp.deployment.pod.id": 45926
  },
  "mutator_correlation_id": "abc123"
}

# Properties

Name Type Required Restrictions Description
attributes object true none Mutator's attributes
mutator_correlation_id string true none HTTP-server local identifier for the mutator.

# Nanoseconds

0

# Properties

Name Type Required Restrictions Description
anonymous integer(int64) false none none

# TimelineId

"497f6eca-6276-4993-bfeb-53cbbbba6f08"

# Properties

Name Type Required Restrictions Description
anonymous string(uuid) false none none

← config →