Endpoints

Requests

Requests

All things related to Spin Cycle requests.

Create and start a new request

POST

/api/v1/requests

Request Parameters

Parameter	Type	Description
type	string	The type of request to create
args	object	The arguments for the request

Sample Request Body

{
  "type": "test",
  "args": {
    "sleepTime": "1000"
  }
}

Sample Response

{
  "id": "bafebl1ddiob71ka5bag",
  "type": "test",
  "state": 1
  "user": "kristen",
  "args": {
    "sleepTime": "1000"
  },
  "createdAt": "2019-03-15T16:49:59Z",
  "startedAt": "2019-03-15T16:49:59Z",
  "finishedAt": "2019-03-15T16:55:42Z",
  "totalJobs": 2,
  "finishedJobs": 0
}

Response Status Codes

201: Successful operation.

400: Invalid request. Either the request type does not exist, or the args are invalid.

401: Unauthorized operation.

503: The Request Manager (RM) API server is in the process of shutting down.

Get a request

GET

/api/v1/requests/${requestId}

Sample Response

{
  "id": "bihqongkp0sg00cq9vo0",
  "type": "test",
  "state": 3,
  "user": "kristen",
  "args": [
    {
      "Pos": 0,
      "Name": "sleepTime",
      "Desc": "How long to sleep (milliseconds) during the request. Useful to verify how RM and JR respond before request has finished.",
      "Type": "optional",
      "Given": true,
      "Default": "1000",
      "Value": "1000"
    }
  ],
  "createdAt": "2019-04-02T18:39:26Z",
  "startedAt": "2019-04-02T18:39:26Z",
  "finishedAt": "2019-04-02T18:39:27Z",
  "JobChain": {
    "requestId": "bihqongkp0sg00cq9vo0",
    "jobs": {
      "3RNT": {
        "id": "3RNT",
        "name": "wait",
        "type": "sleep",
        "bytes": "eyJkdXJhdGlvbiI6MTAwMDAwMDAwMH0=",
        "state": 1,
        "args": {
          "duration": "1000"
        },
        "retry": 0,
        "sequenceId": "FDbP",
        "sequenceRetry": 0
      },
      "eSTn": {
        "id": "eSTn",
        "name": "wait",
        "type": "sleep",
        "bytes": "eyJkdXJhdGlvbiI6MTAwMDAwMDAwMH0=",
        "state": 1,
        "args": {
          "duration": "1000"
        },
        "retry": 0,
        "sequenceId": "cDNR",
        "sequenceRetry": 0
      }
    },
    "adjacencyList": {
      "3RNT": [
        "eSTn"
      ]
    }
  },
  "totalJobs": 2,
  "finishedJobs": 2
}

Response Status Codes

200: Successful operation.

401: Unauthorized operation.

404: Request not found.

Stop a request

PUT

/api/v1/requests/${requestId}/stop

Response Status Codes

200: Successful operation.

401: Unauthorized operation.

404: Request not found.

Get all job logs for a request

GET

/api/v1/requests/${requestId}/log

Sample Response

[
  {
    "requestId": "bihqongkp0sg00cq9vo0",
    "jobId": "3RNT",
    "try": 1,
    "name": "wait",
    "type": "sleep",
    "startedAt": 1554230366094196500,
    "finishedAt": 1554230367094791700,
    "state": 3,
    "exit": 0,
    "error": "",
    "stdout": "",
    "stderr": ""
  },
  {
    "requestId": "bihqongkp0sg00cq9vo0",
    "jobId": "eSTn",
    "try": 1,
    "name": "wait",
    "type": "sleep",
    "startedAt": 1554230366095376600,
    "finishedAt": 1554230367096359700,
    "state": 3,
    "exit": 0,
    "error": "",
    "stdout": "",
    "stderr": ""
  }
]

Response Status Codes

200: Successful operation.

401: Unauthorized operation.

404: Request not found.

Get logs for a specific job in a request

GET

/api/v1/requests/${requestId}/log/${jobId}

Sample Response

{
  "requestId": "bihqongkp0sg00cq9vo0",
  "jobId": "3RNT",
  "try": 1,
  "name": "wait",
  "type": "sleep",
  "startedAt": 1554230366094196500,
  "finishedAt": 1554230367094791700,
  "state": 3,
  "exit": 0,
  "error": "",
  "stdout": "",
  "stderr": ""
}

Response Status Codes

200: Successful operation.

401: Unauthorized operation.

404: Request or job not found.

Get status of all running jobs and requests

GET

/api/v1/status/running

Sample Response

{
  "jobs": [
    {
      "requestId": "bihr0sgkp0sg00cq9vog",
      "jobId": "96i7",
      "type": "sleep",
      "name": "wait",
      "startedAt": 1554231410126312200,
      "state": 2,
      "status": "sleeping",
      "try": 1
    },
    {
      "requestId": "bihr0tgkp0sg00cq9vp0",
      "jobId": "4avk",
      "type": "sleep",
      "name": "wait",
      "startedAt": 1554231414572741000,
      "state": 2,
      "status": "sleeping",
      "try": 1
    }
  ],
  "requests": {
    "bihr0sgkp0sg00cq9vog": {
      "id": "bihr0sgkp0sg00cq9vog",
      "type": "test",
      "state": 2,
      "user": "",
      "createdAt": "2019-04-02T18:56:50Z",
      "startedAt": "2019-04-02T18:56:50Z",
      "finishedAt": null,
      "totalJobs": 2,
      "finishedJobs": 0
    },
    "bihr0tgkp0sg00cq9vp0": {
      "id": "bihr0tgkp0sg00cq9vp0",
      "type": "test",
      "state": 2,
      "user": "",
      "createdAt": "2019-04-02T18:56:55Z",
      "startedAt": "2019-04-02T18:56:55Z",
      "finishedAt": null,
      "totalJobs": 2,
      "finishedJobs": 0
    }
  }
}

Response Status Codes

200: Successful operation.

401: Unauthorized operation.

Find requests that match certain conditions

GET

/api/v1/requests

Requests are returned in descending order by create time (i.e. most recently created first).

Optional Query Parameters

Parameter	Description	Notes
type	The type of request
user	The user who created the request
state	The state of the request	See proto.go — the string name of the state, not the byte. Specify this parameter multiple times to search for multiple states.
arg	The arg/value pair used during request creation	Format: argName=argValue. Specify this parameter multiple times to match on multiple arg/value pairs. (AND logic)
since	Return only requests which were running after this time	Format: 2006-01-02T15:04:05.999999Z07:00
until	Return only requests which were running before this time	Format: 2006-01-02T15:04:05.999999Z07:00
limit	Maximum number of requests to return
offset	Skip this number of requests	Use with limit for pagination of results.

Sample Response

[
  {
    "id": "bihr0sgkp0sg00cq9vog",
    "type": "test",
    "state": 2,
    "user": "Bob",
    "createdAt": "2019-04-02T18:56:50Z",
    "startedAt": "2019-04-02T18:56:50Z",
    "finishedAt": null,
    "totalJobs": 2,
    "finishedJobs": 0
  },
  {
    "id": "bihr0tgkp0sg00cq9vp0",
    "type": "test",
    "state": 3,
    "user": "Alice",
    "createdAt":  "2019-04-02T18:56:55Z",
    "startedAt":  "2019-04-02T18:56:55Z",
    "finishedAt": "2019-04-02T18:57:55Z",
    "totalJobs": 2,
    "finishedJobs": 2
  }
]

Response Status Codes

200: Successful operation.

400: Invalid parameters.

401: Unauthorized operation.

Get list of all available requests

GET

/api/v1/request-list

Sample Response

[
  {
    "Name": "test",
    "Args": [
      {
        "Pos": 0,
        "Name": "sleepTime",
        "Desc": "How long to sleep (milliseconds) during the request. Useful to verify how RM and JR respond before request has finished.",
        "Type": "optional",
        "Given": false,
        "Default": "1000",
        "Value": null
      }
    ]
  }
]

Response Status Codes

200: Successful operation.

401: Unauthorized operation.