Swagger

July 8, 2021 · View on GitHub

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.

Access

Methods

[ Jump to Models ]

Table of Contents

Info

Jobs

Webhooks

Info

get /info
Returns 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" }

Responses

200

Returns success. 
get /
Test to see if service is up
This is an unauthenticated method which returns no data.

Responses

200

Returns success if the service is running.

Jobs

get /jobs
Returns 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.

Query parameters

timeSpanFilter (optional)
Query Parameter — A string which is interpreted as a TimeSpan format: date-span

Return type

array[JobStatus]

Example data

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"
} ]

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

Returns the job status data

404

Not Found ApiError 
delete /jobs/{jobId}
Deletes a job

Path parameters

jobId (required)
Path Parameter — The id which refers to an existing job

Return type

CreateJobResponse

Example data

Content-Type: application/json
{
  "jobId" : "jobId"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

Returns the newly created jobId CreateJobResponse

404

If the job was not found ApiError 
get /jobs/{jobId}
Returns status for the specified job.

Path parameters

jobId (required)
Path Parameter —

Return type

array[JobStatus]

Example data

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"
} ]

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

Returns the job status data

404

If the job was not found ApiError 
post /jobs/{jobId}
Repost a job definition to an existing job.
The existing job must have been created with IsIdling set to true.

Path parameters

jobId (required)
Path Parameter — The id which refers to an existing job

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/json-patch+json
  • application/json
  • text/json
  • application/*+json

Request body

body JobDefinition (optional)
Body Parameter — The new job definition to run

Return type

CreateJobResponse

Example data

Content-Type: application/json
{
  "jobId" : "jobId"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

Returns the newly created jobId CreateJobResponse

400

If there was an error in the request ApiError 
post /jobs
Submit a job definition.

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/json-patch+json
  • application/json
  • text/json
  • application/*+json

Request body

body JobDefinition (optional)
Body Parameter — The new job definition to run

Query parameters

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

Return type

CreateJobResponse

Example data

Content-Type: application/json
{
  "jobId" : "jobId"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

Returns the newly created jobId CreateJobResponse

400

If there was an error in the request ApiError

Webhooks

get /webhooks/events
List all the supported event names.

Responses

200

Success 
get /webhooks
List 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" }

Query parameters

name (optional)
Query Parameter — Name of the webhook "tag"
event (optional)
Query Parameter — Optional query string identifying the event

Responses

200

Returns success.

400

If the event name in the query string is not a supported value

404

If the webhook tag is not found 
post /webhooks
Associates a webhook "tag" with an event and target URL
Sample response: { "WebhookName" : "fooTag" "Event" : "BugFound" "TargetUrl" : "https://mywebhookreceiver" }

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/json-patch+json
  • application/json
  • text/json
  • application/*+json

Request body

body WebHook (optional)
Body Parameter — A WebHook data type

Responses

200

Returns success.

400

Returns bad request if an exception occurs. The exception text will give the reason for the failure. 
put /webhooks
Associates a webhook "tag" with an event and target URL
Sample response: { "WebhookName" : "fooTag" "Event" : "BugFound" "TargetUrl" : "https://mywebhookreceiver" }

Consumes

This API call consumes the following media types via the Content-Type request header:
  • application/json-patch+json
  • application/json
  • text/json
  • application/*+json

Request body

body WebHook (optional)
Body Parameter — A WebHook data type

Responses

200

Returns success.

400

Returns bad request if an exception occurs. The exception text will give the reason for the failure. 
put /webhooks/test/{webhookName}/{eventName}

Path parameters

webhookName (required)
Path Parameter —
eventName (required)
Path Parameter —

Responses

200

Success 
delete /webhooks/{webhookName}/{eventName}
Delete the webhook for a specific event
If the name or event are not found, no error is returned.

Path parameters

webhookName (required)
Path Parameter — Name of the webhook tag
eventName (required)
Path Parameter — Name of the event

Responses

200

Returns success.

400

If the event name is not a supported value.

Models

[ Jump to Methods ]

Table of Contents

  1. AgentConfiguration
  2. ApiError
  3. ApiErrorCode
  4. ApiErrors
  5. AuthenticationMethod
  6. CompileConfiguration
  7. CreateJobResponse
  8. CustomDictionary
  9. FileShareMount
  10. InnerError
  11. JobDefinition
  12. JobState
  13. JobStatus
  14. RESTler
  15. RaftTask
  16. ReplayConfiguration
  17. Resources
  18. RunConfiguration
  19. RunSummary
  20. ApiSpecifications
  21. TargetEndpointConfiguration
  22. WebHook
  23. Webhook
  24. ZAP - ZAP

AgentConfiguration Up

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

ApiError Up

The guidelines specify that the top level structure has only this one member.
error (optional)
ApiErrors

ApiErrorCode Up

ApiErrors Up

code (optional)
ApiErrorCode
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)
InnerError

AuthenticationMethod Up

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

CompileConfiguration Up

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)
CustomDictionary

CreateJobResponse Up

jobId (optional)
String

CustomDictionary Up

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

FileShareMount Up

Mount file share from RAFT storage account to container running a payload.
fileShareName (optional)
String Any fileShare name from the RAFT storage account
mountPath (optional)
String Directory name under which file share is mounted on the container. For example "/my-job-config"

InnerError Up

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

JobDefinition Up

RAFT job run definition
apiSpecifications (optional)
ApiSpecifications
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)
Resources
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)
Webhook
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.

JobState Up

JobStatus Up

tool (optional)
String
jobId (optional)
String
state (optional)
JobState
metrics (optional)
RunSummary
utcEventTime (optional)
Date format: date-time
details (optional)
map[String, String]
agentName (optional)
String

RESTler Up

RESTler payload
task (optional)
String Can be compile, fuzz, test, replay
Enum:
compile
test
fuzz
replay
compileConfiguration (optional)
CompileConfiguration
runConfiguration (optional)
RunConfiguration
replayConfiguration (optional)
ReplayConfiguration
agentConfiguration (optional)
AgentConfiguration

RaftTask Up

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: /*?:|&lt;&gt;"
apiSpecifications (optional)
ApiSpecifications
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)
AuthenticationMethod
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)

ReplayConfiguration Up

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.

Resources Up

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

RunConfiguration Up

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)
TargetEndpointConfiguration
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

RunSummary Up

totalRequestCount (optional)
Integer format: int32
responseCodeCounts (optional)
map[String, Integer] format: int32
totalBugBucketsCount (optional)
Integer format: int32

ApiSpecifications Up

url (optional)
String
filePath (optional)
String

TargetEndpointConfiguration Up

Configuration of the endpoint under test
ip (optional)
String The IP of the endpoint being fuzzed
port (optional)
Integer The port of the endpoint being fuzzed. Defaults to 443. format: int32

WebHook Up

webhookName (optional)
String
event (optional)
String
targetUrl (optional)
String format: uri

Webhook Up

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

ZAP - ZAP Up