The RAFT REST API is represented in a UI that can be viewed at your https://<raft-service-endpoint>/swagger. This UI also will display the schema's for the various supported methods.
Listed below is a static view of the swagger methods.
[ Jump to Models ]get /webhooks/eventsget /webhookspost /webhooksput /webhooksput /webhooks/test/{webhookName}/{eventName}delete /webhooks/{webhookName}/{eventName}
get /infoReturns information about the system.
This is an unauthenticated method.
Sample response:
{
"version": "1.0.0.0",
"serviceStartTime": "2020-07-02T15:28:57.0093727+00:00"
}
Returns success.
get /Test to see if service is up
This is an unauthenticated method which returns no data.
Returns success if the service is running.
get /jobsReturns in an array status for all jobs over the last 24 hours.
The default timespan is over the last 24 hours. Use the query string timeSpanFilter="TimeSpan" to specify a different interval.
Use a time format that can be parsed as a TimeSpan data type.
If no data is found the result will be an empty array.
timeSpanFilter (optional)
Query Parameter — A string which is interpreted as a TimeSpan format: date-span
array[JobStatus]
Content-Type: application/json
[ {
"jobId" : "jobId",
"agentName" : "agentName",
"utcEventTime" : "2000-01-23T04:56:07.000+00:00",
"details" : {
"key" : "details"
},
"state" : "Creating",
"metrics" : {
"responseCodeCounts" : {
"key" : 6
},
"totalRequestCount" : 0,
"totalBugBucketsCount" : 1
},
"tool" : "tool"
}, {
"jobId" : "jobId",
"agentName" : "agentName",
"utcEventTime" : "2000-01-23T04:56:07.000+00:00",
"details" : {
"key" : "details"
},
"state" : "Creating",
"metrics" : {
"responseCodeCounts" : {
"key" : 6
},
"totalRequestCount" : 0,
"totalBugBucketsCount" : 1
},
"tool" : "tool"
} ]application/json
delete /jobs/{jobId}Deletes a job
jobId (required)
Path Parameter — The id which refers to an existing job
Content-Type: application/json
{
"jobId" : "jobId"
}application/json
get /jobs/{jobId}Returns status for the specified job.
jobId (required)
Path Parameter —
array[JobStatus]
Content-Type: application/json
[ {
"jobId" : "jobId",
"agentName" : "agentName",
"utcEventTime" : "2000-01-23T04:56:07.000+00:00",
"details" : {
"key" : "details"
},
"state" : "Creating",
"metrics" : {
"responseCodeCounts" : {
"key" : 6
},
"totalRequestCount" : 0,
"totalBugBucketsCount" : 1
},
"tool" : "tool"
}, {
"jobId" : "jobId",
"agentName" : "agentName",
"utcEventTime" : "2000-01-23T04:56:07.000+00:00",
"details" : {
"key" : "details"
},
"state" : "Creating",
"metrics" : {
"responseCodeCounts" : {
"key" : 6
},
"totalRequestCount" : 0,
"totalBugBucketsCount" : 1
},
"tool" : "tool"
} ]application/json
post /jobs/{jobId}Repost a job definition to an existing job.
The existing job must have been created with IsIdling set to true.
jobId (required)
Path Parameter — The id which refers to an existing job
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
body JobDefinition (optional)
Body Parameter — The new job definition to run
Content-Type: application/json
{
"jobId" : "jobId"
}application/json
post /jobsSubmit a job definition.
This API call consumes the following media types via the Content-Type request header:
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
body JobDefinition (optional)
Body Parameter — The new job definition to run
region (optional)
Query Parameter — Run the job definition in a specified region. If not set - run in the same region as the service
https://docs.microsoft.com/en-us/azure/container-instances/container-instances-region-availability
Content-Type: application/json
{
"jobId" : "jobId"
}application/json
get /webhooksList the webhooks associated with the tag. Optionally provide an event in the query string to just show that one event.
Sample response:
{
"WebhookName" : "fooTag"
"Event" : "BugFound"
"TargetUrl" : "https://mywebhookreceiver"
}
name (optional)
Query Parameter — Name of the webhook "tag"
event (optional)
Query Parameter — Optional query string identifying the event
post /webhooksAssociates a webhook "tag" with an event and target URL
Sample response:
{
"WebhookName" : "fooTag"
"Event" : "BugFound"
"TargetUrl" : "https://mywebhookreceiver"
}
This API call consumes the following media types via the Content-Type request header:
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
body WebHook (optional)
Body Parameter — A WebHook data type
put /webhooksAssociates a webhook "tag" with an event and target URL
Sample response:
{
"WebhookName" : "fooTag"
"Event" : "BugFound"
"TargetUrl" : "https://mywebhookreceiver"
}
This API call consumes the following media types via the Content-Type request header:
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
body WebHook (optional)
Body Parameter — A WebHook data type
put /webhooks/test/{webhookName}/{eventName}webhookName (required)
Path Parameter —
eventName (required)
Path Parameter —
delete /webhooks/{webhookName}/{eventName}Delete the webhook for a specific event
If the name or event are not found, no error is returned.
webhookName (required)
Path Parameter — Name of the webhook tag
eventName (required)
Path Parameter — Name of the event
[ Jump to Methods ]
AgentConfigurationApiErrorApiErrorCodeApiErrorsAuthenticationMethodCompileConfigurationCreateJobResponseCustomDictionaryFileShareMountInnerErrorJobDefinitionJobStateJobStatusRESTlerRaftTaskReplayConfigurationResourcesRunConfigurationRunSummaryApiSpecificationsTargetEndpointConfigurationWebHookWebhookZAP- ZAP
Configure behaviour of RESTler agent
resultsAnalyzerReportTimeSpanInterval (optional)
String How often to run result analyzer against RESTler logs. Default is every 1 minute.
If not set then result analyzer will run only once after RESTler task is over. format: date-span
The guidelines specify that the top level structure has only this one member.
error (optional)
code (optional)
message (optional)
String A detail string that can be used for debugging
target (optional)
String Function name that generated the error
details (optional)
array[ApiErrors] An array of details about specific errors that led to this reported error.
innerError (optional)
Method of authenticating with the service under test
msal (optional)
String KeyVault Secret name containing MSAL authentication information in following format:
{ "tenant" : "<tenantId>", "client" : "<clientid>", "secret" : "<secret>"}
optional values that could be passed as part of the JSON: scopes and authorityUri
commandLine (optional)
String Command line to execute that acquires authorization token and prints it to standard output
txtToken (optional)
String KeyVault Secret name containing plain text token
User-specified RESTler compiler configuration
inputJsonGrammarPath (optional)
String Path to a JSON grammar to use for compilation
If set then JSON grammar used for compilation instead of Swagger
inputFolderPath (optional)
String Grammar is produced by compile step prior. The compile step
file share is mounted and set here. Agent will not modify
this share. Agent will make a copy of all needed files to it's work directory
and re-run compile with data passed through this folder.
readOnlyFuzz (optional)
Boolean When true, only fuzz the GET requests
allowGetProducers (optional)
Boolean Allows GET requests to be considered.
This option is present for debugging, and should be
set to 'false' by default.
In limited cases when GET is a valid producer, the user
should add an annotation for it.
useRefreshableToken (optional)
Boolean Use refreshable token for authenticating with service under test
trackFuzzedParameterNames (optional)
Boolean True by default. Every fuzzable primitive will include an additional parameter param_name which is the name of the property or parameter being fuzzed. These will be used to capture fuzzed parameters iin tracked_parameters in the spec coverage file
mutationsSeed (optional)
Long Use the seed to generate random value for empty/null customDictitonary fields
if not set then default hard-coded RESTler values are used for populating customDictionary fields format: int64
customDictionary (optional)
jobId (optional)
fuzzableString (optional)
array[String] List of string values used as fuzzing inputs. If null then values are auto-generated
fuzzableInt (optional)
array[String] List of int values used as fuzzing inputs. If null then values are auto-generated
fuzzableNumber (optional)
array[String] List of number values used as fuzzing inputs. If null then values are auto-generated
fuzzableBool (optional)
array[String] List of bool values used as fuzzing inputs. If null then values are auto-generated
fuzzableDatetime (optional)
array[String] List of date-time values used as fuzzing inputs. If null then values are auto-generated
fuzzableObject (optional)
array[String] List of string encoded JSON objects values used as fuzzing inputs
fuzzableUuid4 (optional)
array[String] List of UUID4 values used as fuzzing inputs
customPayload (optional)
map[String, array[String]] Map of values to use as replacement of parameters defined in Swagger specifications. For example
if { "userId" : ["a", "b"] } is specified then {userId} in URL path /users/{userId} will be replaced
by "a" or by "b"
customPayloadUuid4Suffix (optional)
map[String, String] Map of values to use as replacement of parameters defined in swagger. The values will
have a random suffix added. For example {"publicIpAddressName": "publicIpAddrName-"} will produce publicIpAddrName-f286a0a069 for
publicIpAddressName parameter defined in Swagger specifications.
customPayloadHeader (optional)
map[String, array[String]] User specified custom headers to pass in every request
shadowValues (optional)
map[String, map[String, array[String]]] RESTler documentation will have more info on this
Mount file share from RAFT storage account to container running a payload.
Inner error can be used for cascading exception handlers or where there are field validations
and multiple errors need to be returned.
message (optional)
String Inner detailed message
RAFT job run definition
apiSpecifications (optional)
namePrefix (optional)
String String used as a prefix added to service generated job ID.
Prefix can contain only lowercase letters, numbers, and hyphens, and must begin with a letter or a number.
Prefix cannot contain two consecutive hyphens.
Can be up to 27 characters long
resources (optional)
tasks
array[RaftTask] RAFT Task definitions
duration (optional)
String Duration of the job; if not set, then job runs till completion (or forever).
For RESTler jobs - time limit is only useful for Fuzz task format: date-span
host (optional)
String Override the Host for each request.
webhook (optional)
rootFileShare (optional)
String If set, then place all job run results into this file share
readOnlyFileShareMounts (optional)
array[FileShareMount] File shares to mount from RAFT deployment storage account as read-only directories.
readWriteFileShareMounts (optional)
array[FileShareMount] File shares to mount from RAFT deployment storage account as read-write directories.
tool (optional)
jobId (optional)
state (optional)
metrics (optional)
utcEventTime (optional)
Date format: date-time
details (optional)
agentName (optional)
RESTler payload
task (optional)
String Can be compile, fuzz, test, replay
Enum:
compile
test
fuzz
replay
compileConfiguration (optional)
runConfiguration (optional)
replayConfiguration (optional)
agentConfiguration (optional)
RAFT task to run.
toolName
String Tool defined by folder name located in cli/raft-tools/tools/{ToolName}
outputFolder
String Output folder name to store agent generated output
Must not contain: /*?:|<>"
apiSpecifications (optional)
host (optional)
String Override the Host for each request.
isIdling (optional)
Boolean If true - do not run the task. Idle container to allow user to connect to it.
duration (optional)
String Duration of the task; if not set, then job level duration is used.
For RESTler jobs - time limit is only useful for Fuzz task format: date-span
authenticationMethod (optional)
keyVaultSecrets (optional)
array[String] List of names of secrets in Keyvault used in configuring
authentication credentials
Key Vault secret name must start with alphabetic character and
followed by a string of alphanumeric characters (for example 'MyName123').
Secret name can be upto 127 characters long
toolConfiguration (optional)
RESTler configuration for replaying request sequences that triggered a reproducable bug
bugBuckets (optional)
array[String] List of paths to RESTler folder runs to replay (names of folders are assigned when mounted readonly/readwrite file share mounts).
If path is a folder, then all bug buckets replayed in the folder.
If path is a bug_bucket file - then only that file is replayed.
If empty - then replay all bugs under RunConfiguration.previousStepOutputFolderPath.
Hardware resources to allocate for the job
cores (optional)
Integer Number of cores to allocate for the job.
Default is 1 core.
see: https://docs.microsoft.com/en-us/azure/container-instances/container-instances-region-availability format: int32
memoryGBs (optional)
Integer Memory to allocate for the job
Default is 1 GB.
see: https://docs.microsoft.com/en-us/azure/container-instances/container-instances-region-availability format: int32
RESTler job Test, TestFuzzLean, TestAllCombinations, Fuzz or Replay configuration
grammarPy (optional)
String Path to grammar py relative to compile folder path. If not set then default "grammar.py" grammar is assumed
inputFolderPath (optional)
String For Test or Fuzz tasks: Grammar is produced by compile step. The compile step
file share is mounted and set here. Agent will not modify
this share. Agent will make a copy of all needed files to it's work directory.
For Replay task: path to RESTler Fuzz or Test run that contains bug buckets to replay
targetEndpointConfiguration (optional)
producerTimingDelay (optional)
Integer The delay in seconds after invoking an API that creates a new resource format: int32
useSsl (optional)
Boolean Use SSL when connecting to the server
pathRegex (optional)
String Path regex for filtering tested endpoints
authenticationTokenRefreshIntervalSeconds (optional)
Integer Authentciation token refresh interval format: int32
ignoreBugHashes (optional)
array[String] List of bug hashes to ignore when posting Bug Found webhook
maxRequestExecutionTime (optional)
Integer Maximum request execution time
ignoreDependencies (optional)
Boolean Ignore resource dependencies
ignoreFeedback (optional)
Boolean Ignore feedback from responses
totalRequestCount (optional)
Integer format: int32
responseCodeCounts (optional)
map[String, Integer] format: int32
totalBugBucketsCount (optional)
Integer format: int32
Configuration of the endpoint under test
Webhook definition
name (optional)
String Webhook name to associate with the job
metadata (optional)
map[String, String] Arbitrary key/value pairs that will be returned in webhooks