LOCKSS Poller Service REST API

API of the LOCKSS Poller REST Service
More information: https://www.lockss.org/
Contact Info: lockss-support@lockss.org
Version: 1.0.0
BasePath:/
BSD-3-Clause
https://www.lockss.org/support/open-source-license/

Access

  1. HTTP Basic Authentication

Methods

[ Jump to Models ]

Table of Contents

PollDetail

PollerPolls

Service

VoterPolls

PollDetail

Up
get /polls/{pollKey}/peer/{peerId}
Poll Peer Data (getPollPeerVoteUrls)

Path parameters

pollKey (required)
Path Parameter — The pollKey from the PollDetail.
peerId (required)
Path Parameter — The peerId from the Poll Detail.PeerData.

Query parameters

urls (required)
Query Parameter — The voter urls to return.
page (optional)
Query Parameter — The page number
size (optional)
Query Parameter — The page size

Return type

UrlPager

Example data

Content-Type: application/json
{
  "pageDesc" : {
    "total" : 150,
    "size" : 5,
    "nextPage" : "nextPage",
    "prevPage" : "prevPage",
    "page" : 10
  },
  "urls" : [ "urls", "urls" ]
}

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.

Responses

200

A pagable list of voter urls with a given status. UrlPager

404

Poll or Voter ID not found.

500

Internal Server Error

Up
get /polls/{pollKey}/repairs
Poll Repairs (getRepairQueueData)

Path parameters

pollKey (required)
Path Parameter — The pollKey as listed in the PollDetail object.

Query parameters

repair (required)
Query Parameter — The repair queue elements to return.
page (optional)
Query Parameter — The page number.
size (optional)
Query Parameter — The size of the page.

Return type

RepairPager

Example data

Content-Type: application/json
{
  "repairs" : [ {
    "result" : "NoQuorum",
    "repairUrl" : "repairUrl",
    "repairFrom" : "repairFrom"
  }, {
    "result" : "NoQuorum",
    "repairUrl" : "repairUrl",
    "repairFrom" : "repairFrom"
  } ],
  "pageDesc" : {
    "total" : 150,
    "size" : 5,
    "nextPage" : "nextPage",
    "prevPage" : "prevPage",
    "page" : 10
  }
}

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.

Responses

200

A pagable list of repair queue elements. RepairPager

404

Poll ID not found.

500

Internal Server Error

Up
get /polls/{pollKey}/tallies
Page Tally (getTallyUrls)

Path parameters

pollKey (required)
Path Parameter — The pollKey as listed in the PollDetail object.

Query parameters

tally (required)
Query Parameter — The kind of tally element to return.
page (optional)
Query Parameter — The page number.
size (optional)
Query Parameter — The size of the page.

Return type

UrlPager

Example data

Content-Type: application/json
{
  "pageDesc" : {
    "total" : 150,
    "size" : 5,
    "nextPage" : "nextPage",
    "prevPage" : "prevPage",
    "page" : 10
  },
  "urls" : [ "urls", "urls" ]
}

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.

Responses

200

A pagable list of urls for given tally type. UrlPager

404

Poll Key not found.

500

Internal Server Error

PollerPolls

Up
get /polls/poller/{pollKey}
PollerDetails (getPollerPollDetails)
Return the detailed information about a poll.

Path parameters

pollKey (required)
Path Parameter — The key assigned by the PollManager.

Return type

PollerDetail

Example data

Content-Type: application/json
{
  "noAuPeers" : [ "noAuPeers", "noAuPeers" ],
  "pollerId" : "pollerId",
  "pollDesc" : {
    "auId" : "auId",
    "cuSetSpec" : {
      "upperBound" : "upperBound",
      "urlPrefix" : "urlPrefix",
      "lowerBound" : "lowerBound"
    },
    "protocol" : 6,
    "pollType" : 3,
    "variant" : "PoR",
    "pluginPollVersion" : "pluginPollVersion",
    "modulus" : 1
  },
  "quorum" : 3,
  "pollKey" : "pollKey",
  "votedPeers" : [ {
    "peerId" : "peerId",
    "lastStateChange" : 9,
    "agreement" : 2.027123,
    "pollerOnlyLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "bytesRead" : 6,
    "bytesHashed" : 1,
    "wtNumDisagree" : 4.9652185,
    "voterOnlyLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "wtNumVoterOnly" : 9.965781,
    "disagreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numVoterOnly" : 1,
    "numAgree" : 4,
    "state" : "state",
    "agreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numPollerOnly" : 1,
    "wtAgreement" : 7.4577446,
    "wtNumAgree" : 1.1730742,
    "wtNumPollerOnly" : 5.025005,
    "status" : "status",
    "numDisagree" : 7
  }, {
    "peerId" : "peerId",
    "lastStateChange" : 9,
    "agreement" : 2.027123,
    "pollerOnlyLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "bytesRead" : 6,
    "bytesHashed" : 1,
    "wtNumDisagree" : 4.9652185,
    "voterOnlyLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "wtNumVoterOnly" : 9.965781,
    "disagreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numVoterOnly" : 1,
    "numAgree" : 4,
    "state" : "state",
    "agreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numPollerOnly" : 1,
    "wtAgreement" : 7.4577446,
    "wtNumAgree" : 1.1730742,
    "wtNumPollerOnly" : 5.025005,
    "status" : "status",
    "numDisagree" : 7
  } ],
  "voteMargin" : 5,
  "voteDuration" : 7,
  "duration" : 6,
  "voteDeadline" : 2,
  "repairQueue" : {
    "numActive" : 5,
    "activeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numCompleted" : 6,
    "pendingLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numPending" : 6,
    "completedLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    }
  },
  "createTime" : 0,
  "outerCircleTarget" : 5,
  "pollEnd" : 9,
  "deadline" : 1,
  "tally" : {
    "errorLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numNoQuorum" : 6,
    "wtTooClose" : 2.8841622,
    "noQuorumLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "wtNoQuorum" : 6.778325,
    "disagreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "tooCloseLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numTooClose" : 9,
    "numAgree" : 6,
    "wtDisagreed" : 1.284659,
    "agreeLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "numError" : 3,
    "numDisagree" : 8,
    "wtAgreed" : 6.965118
  },
  "hashAlgorithm" : "hashAlgorithm",
  "status" : "status",
  "errorDetails" : "errorDetails"
}

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.

Responses

200

Detailed poll info returned. PollerDetail

401

Unauthorized request.

404

Poll Key not found.

500

Internal Server Error

Up
get /polls/poller
Get the list of recent polls as poller. (getPollsAsPoller)
Get the list of recent polls as poller from the poll queue. if size and page are passed in use those arguments to limit return data.

Query parameters

size (optional)
Query Parameter — Size of the page to retrieve. format: int32
page (optional)
Query Parameter — Number of the page to retrieve. format: int32

Return type

PollerPager

Example data

Content-Type: application/json
{
  "pageDesc" : {
    "total" : 150,
    "size" : 5,
    "nextPage" : "nextPage",
    "prevPage" : "prevPage",
    "page" : 10
  },
  "polls" : [ {
    "numCompletedRepairs" : 5,
    "auId" : "auId",
    "numHashErrors" : 1,
    "numTalliedUrls" : 6,
    "start" : 2,
    "pollKey" : "pollKey",
    "variant" : "variant",
    "numAgreeUrls" : 5,
    "pollEnd" : 9,
    "deadline" : 7,
    "detailLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "status" : "status",
    "participants" : 0
  }, {
    "numCompletedRepairs" : 5,
    "auId" : "auId",
    "numHashErrors" : 1,
    "numTalliedUrls" : 6,
    "start" : 2,
    "pollKey" : "pollKey",
    "variant" : "variant",
    "numAgreeUrls" : 5,
    "pollEnd" : 9,
    "deadline" : 7,
    "detailLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "status" : "status",
    "participants" : 0
  } ]
}

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.

Responses

200

A pagable list has been returned. PollerPager

401

Unauthorized request

500

Internal Server Error

Service

Up
post /polls
Send a request to call a poll to the poller (callPoll)
Use the information found in the descriptor object to initiate a poll.

Consumes

This API call consumes the following media types via the Content-Type request header:

Request body

body PollDesc (required)
Body Parameter

Return type

String

Example data

Content-Type: application/json
""

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.

Responses

202

The Poll request has been accepted and added to the queue. String

401

The Request is unauthorized

403

The Au is not eligible for polling

404

The descriptor (au) can not be found.

500

Internal Server Error

Up
delete /polls/{psId}
Stop a poll and remove from queue. (cancelPoll)
Stop a running poll and delete any schecduled polls for poll with the poll service id.

Path parameters

psId (required)
Path Parameter

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.

Responses

200

Poll successfully stopped

401

Unauthorized request

404

No poll found with that id

500

Internal Server Error

Up
get /polls/{psId}
Get queued poll status (getPollStatus)
Get the status of a previously queued poll.

Path parameters

psId (required)
Path Parameter

Return type

PollerSummary

Example data

Content-Type: application/json
{
  "numCompletedRepairs" : 5,
  "auId" : "auId",
  "numHashErrors" : 1,
  "numTalliedUrls" : 6,
  "start" : 2,
  "pollKey" : "pollKey",
  "variant" : "variant",
  "numAgreeUrls" : 5,
  "pollEnd" : 9,
  "deadline" : 7,
  "detailLink" : {
    "link" : "http:www.example.com/v1/element",
    "desc" : "pollerOnly"
  },
  "status" : "status",
  "participants" : 0
}

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.

Responses

200

Poll info returned. PollerSummary

401

Unauthorized request

404

No such poll service id.

500

Internal Server Error

Up
get /status
Get the status of the service (getStatus)
Get the status of the service

Return type

apiStatus

Example data

Content-Type: application/json
{
  "ready" : true,
  "version" : "version"
}

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.

Responses

200

The status of the service apiStatus

401

Unauthorized request

500

Internal server error

503

Some or all of the system is not available

VoterPolls

Up
get /polls/voter
Get the list of recent voter only polls. (getPollsAsVoter)
Get the list of recent polls as voter from the poll queue. if size and page are passed in use those arguments to limit return data.

Query parameters

size (optional)
Query Parameter — Size of the page to retrieve. format: int32
page (optional)
Query Parameter — Number of the page to retrieve. format: int32

Return type

VoterPager

Example data

Content-Type: application/json
{
  "pageDesc" : {
    "total" : 150,
    "size" : 5,
    "nextPage" : "nextPage",
    "prevPage" : "prevPage",
    "page" : 10
  },
  "polls" : [ {
    "auId" : "auId",
    "caller" : "caller",
    "start" : 0,
    "pollKey" : "pollKey",
    "deadline" : 6,
    "detailLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "status" : "status"
  }, {
    "auId" : "auId",
    "caller" : "caller",
    "start" : 0,
    "pollKey" : "pollKey",
    "deadline" : 6,
    "detailLink" : {
      "link" : "http:www.example.com/v1/element",
      "desc" : "pollerOnly"
    },
    "status" : "status"
  } ]
}

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.

Responses

200

A pagable list has been returned. VoterPager

401

Unauthorized request

500

Internal Server Error

Up
get /polls/voter/{pollKey}
VoterDetails (getVoterPollDetails)
Return the detailed information about a poll.

Path parameters

pollKey (required)
Path Parameter — The key assigned by the PollManager.

Return type

VoterDetail

Example data

Content-Type: application/json
{
  "pollerNonce" : "pollerNonce",
  "pollerId" : "pollerId",
  "agreement" : 5.962133916683182,
  "pollDesc" : {
    "auId" : "auId",
    "cuSetSpec" : {
      "upperBound" : "upperBound",
      "urlPrefix" : "urlPrefix",
      "lowerBound" : "lowerBound"
    },
    "protocol" : 6,
    "pollType" : 3,
    "variant" : "PoR",
    "pluginPollVersion" : "pluginPollVersion",
    "modulus" : 1
  },
  "wtSymmetricAgreement" : 7.061401241503109,
  "pollKey" : "pollKey",
  "voterNonce" : "voterNonce",
  "duration" : 6,
  "voteDeadline" : 9,
  "createTime" : 0,
  "voter2Nonce" : "voter2Nonce",
  "numVoterOnly" : 7,
  "symmetricAgreement" : 2.3021358869347655,
  "numAgree" : 3,
  "callerId" : "callerId",
  "deadline" : 1,
  "wtAgreement" : 5.637376656633329,
  "numPollerOnly" : 4,
  "hashAlgorithm" : "hashAlgorithm",
  "status" : "status",
  "numDisagree" : 2,
  "errorDetails" : "errorDetails"
}

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.

Responses

200

Detailed poll info returned. VoterDetail

401

Unauthorized request

404

No such poll key.

500

Internal Server Error

Models

[ Jump to Methods ]

Table of Contents

  1. CachedUriSetSpec -
  2. LinkDesc -
  3. PageDesc -
  4. PeerData -
  5. PollDesc -
  6. PollerDetail -
  7. PollerPager -
  8. PollerSummary -
  9. RepairData -
  10. RepairPager -
  11. RepairQueue -
  12. TallyData -
  13. UrlPager -
  14. VoterDetail -
  15. VoterPager -
  16. VoterSummary -
  17. apiStatus -

CachedUriSetSpec - Up

A set of urls bounded by upper and lower restraints. If lower = "." this is a singleContentNode. If lower is null then start at the root url, if upper is null end with the last.
urlPrefix
String The base which roots the lower and upper bound
lowerBound (optional)
String lower bound of the prefix range, inclusive.
upperBound (optional)
String upper bound of prefix range, inclusive.

LinkDesc - Up

link
String The actual link suitable for a standard GET request
desc (optional)
String A description of this link

PageDesc - Up

The information needed to page in a long list of data
page
Integer The page number
size
Integer The size or number of elements on a page
total
Integer The mTotal number of elements.
prevPage (optional)
String The url of the prev page of results or null
nextPage (optional)
String The url to the next page of results or null.

PeerData - Up

Detail for a single voter in a poll.
peerId
String the peer id for this participant
status
String the status of this peer
agreement (optional)
Float the percentage of vote agreement. format: float
numAgree (optional)
Long format: int64
agreeLink (optional)
numDisagree (optional)
Long format: int64
disagreeLink (optional)
numPollerOnly (optional)
Long format: int64
pollerOnlyLink (optional)
numVoterOnly (optional)
Long format: int64
voterOnlyLink (optional)
bytesHashed (optional)
Long the number of bytes hashed. format: int64
bytesRead (optional)
Long the number of bytes read. format: int64
wtAgreement (optional)
Float the weight of vote percentage agreement. format: float
wtNumAgree (optional)
Float the weight of number agree votes. format: float
wtNumDisagree (optional)
Float the weight of number of disagree votes. format: float
wtNumPollerOnly (optional)
Float the weight of number of poller only votes. format: float
wtNumVoterOnly (optional)
Float the weight of number of voter only votes. format: float
state (optional)
String the state machine state.
lastStateChange (optional)
Long the time of last state change. format: int64

PollDesc - Up

The Poller Services poll spec used to define a poll.
auId
String The id which defines the poll
cuSetSpec (optional)
pollType (optional)
Integer The type of poll to run. Only V3 is supported.
protocol (optional)
Integer The version of polling protocol.
pluginPollVersion (optional)
String The version of the polling features needed by the plugin.
variant (optional)
String The V3 poll variation.
Enum:
PoR
PoP
Local
NoPoll
modulus (optional)
Integer Poll on every 'n'th url.

PollerDetail - Up

The details of a poll being performed or queued by the Poller
pollDesc
pollerId
String The id of the poller who called the poll
status
String The current status of the poll.
pollKey (optional)
String Key generated by poll manager when poll is created.
createTime (optional)
Long The timestamp at which the poll was created. format: int64
duration (optional)
Long The estimated duration for the poll. format: int64
deadline (optional)
Long The time by which the poll must have completed format: int64
outerCircleTarget (optional)
Integer The number of peers from the poller outer circle to taget. format: int32
hashAlgorithm (optional)
String The algorithm used by the hasher for this poll.
voteMargin (optional)
Integer The required agreement need to decide landslide agreement or disagreement. format: int32
voteDeadline (optional)
Long The time by which all voters must have voted. format: int64
voteDuration (optional)
Long The estimated duration for voters. format: int64
pollEnd (optional)
Long the time at which the poll ended or -1 if still running. format: int64
quorum (optional)
Integer The minimum required for a quroum format: int32
errorDetails (optional)
String The error which caused the poll to fail.
votedPeers (optional)
array[PeerData] The data from peers whom voted.
noAuPeers (optional)
array[String] The peers who do not have the au.
tally (optional)
repairQueue (optional)

PollerPager - Up

A page of poller poll summaries.
pageDesc
polls (optional)
array[PollerSummary] The list of polls for the current page or null

PollerSummary - Up

A summary of a poll in which we are the poller.
auId
String The id for the au being polled.
variant
String The V3 Poll variant.
status
String The current status of the poll.
participants (optional)
Integer The number of participants voting. format: int32
numTalliedUrls (optional)
Integer The number of tallied urls. format: int32
numHashErrors (optional)
Integer The number of hash errors. format: int32
numCompletedRepairs (optional)
Integer The number of completed repairs. format: int32
numAgreeUrls (optional)
Integer The number of urls with agreement. format: int32
start
Long The timestamp for when the poll started. format: int64
deadline
Long The deadline for voting in this poll. format: int64
pollEnd (optional)
Long The time at which the poll ended. format: int64
pollKey
String Key generated by poll manager when poll was created.
detailLink (optional)

RepairData - Up

structure used to define a repair source for url. if the source is null than repair from publisher
repairUrl
String The url to repair
repairFrom
String The peer to repair from
result (optional)
String The status of this repair
Enum:
NoQuorum
TooClose
Lost
LostPollerOnly
LostVoterOnly
Won

RepairPager - Up

A Pager for a list of urls found in poll details.
pageDesc
repairs (optional)
array[RepairData] The list of repair data on this page or null.

RepairQueue - Up

Description of the RepairQueue.
numPending
Integer The number of pending repairs format: int32
pendingLink (optional)
numActive
Integer The number of active repairs format: int32
activeLink (optional)
numCompleted
Integer The number of completed repairs format: int32
completedLink (optional)

TallyData - Up

The tally for the current poll.
numAgree
Integer The number of urls with agreement. format: int32
agreeLink (optional)
numDisagree
Integer The number of urls with disagreement. format: int32
disagreeLink (optional)
numTooClose
Integer The number of urls too close. format: int32
tooCloseLink (optional)
numNoQuorum
Integer The number of urls without enough voters. format: int32
noQuorumLink (optional)
numError
Integer The number of urls without errors. format: int32
errorLink (optional)
wtAgreed (optional)
Float The weighted sum agreed uris. format: float
wtDisagreed (optional)
Float The weighted sum of disagree uris. format: float
wtTooClose (optional)
Float The sum of the tooClose uris. format: float
wtNoQuorum (optional)
Float The weighted sum of NoQuorum uris. format: float

UrlPager - Up

A Pager for a list of urls found in poll details.
pageDesc
urls (optional)
array[String] The urls on this page.

VoterDetail - Up

The details of a poll being performed or queued as the Voter.
pollDesc
pollerId
String The id of the voter in the poll
callerId (optional)
String The id of the poller who called the poll
status
String The current status of the poll.
pollKey (optional)
String Key generated by poll manager when poll is created.
createTime (optional)
Long The timestamp at which the poll was created. format: int64
duration (optional)
Long The estimated duration for the poll. format: int64
deadline (optional)
Long The time by which the poll must have completed format: int64
hashAlgorithm (optional)
String The algorithm used by the hasher for this poll.
agreement (optional)
Double The percentage agreement. format: double
wtAgreement (optional)
Double The weighted percentage agreement. format: double
symmetricAgreement (optional)
Double The percentage of symmetric agreement. format: double
wtSymmetricAgreement (optional)
Double The weighted percentage of symmetric agreement. format: double
pollerNonce (optional)
String the poller nonce
voterNonce (optional)
String the voter nonce
voter2Nonce (optional)
String the voter2 nonce
voteDeadline (optional)
Long The time by which all voters must have voted. format: int64
numAgree (optional)
Integer The number of urls with agreement. format: int32
numDisagree (optional)
Integer The number of urls with disagreement. format: int32
numPollerOnly (optional)
Integer The number of urls found by only the poller. format: int32
numVoterOnly (optional)
Integer The number of urls found by only a voter. format: int32
errorDetails (optional)
String The error which caused the poll to fail.

VoterPager - Up

A page of voter poll summary.
pageDesc
polls (optional)
array[VoterSummary] The list of polls for the current page or null

VoterSummary - Up

A summary of a poll in which we are acting just as a voter.
auId
String The id for the au being polled.
caller
String The id of who called the poll.
start
Long The timestamp for when the poll started. format: int64
status
String The current status of the poll.
deadline
Long The deadline for voting in this poll. format: int64
pollKey
String Key generated by poll manager when poll was created.
detailLink (optional)

apiStatus - Up

The status information of the service
version
String The version of the service
ready
Boolean The indication of whether the service is available