search

opensquare-network / collaboration

OpenSquare collaboration platform
Apache License 2.0
3 stars 4 forks source link

Create api docs for Polkassembly integration #354

Open wliyongfeng opened 2 years ago

wliyongfeng commented 2 years ago

The high priority apis includes:

For fast collaboration, we can first leave the docs on this issue. @hyifeng

hyifeng commented 2 years ago

API Endpoints for testing

1. Get the proposal list for one space, including active, pending, closed ones.

GET /api/[spaceName]/proposals?page=[pageIndex]&page_size=[pageSize]

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - pageIndex: The pagination index from 1 to N
  - pageSize: The items count per page

Response:

{
  "items": [
    {
       "_id": "619db5558edbaeb5e1620166",
      "space": "polkadot",
      "title": "The proposal title",
      "content": "This is the proposal description",
      "contentType": "markdown",
      "choiceType": "single",
      "choices": [
        "Aye",
        "Nay"
      ],
      "startDate": 1637683200000,
      "endDate": 1638201600000,
      "snapshotHeight": 7837243,
      "weightStrategy": [
        "balance-of",
        "quadratic-balance-of"
      ],
      "data": {
        "space": "polkadot",
        "title": "The proposal title",
        "content": "This is the proposal description",
        "contentType": "markdown",
        "choiceType": "single",
        "choices": [
          "Aye",
          "Nay"
        ],
        "startDate": 1637683200000,
        "endDate": 1638201600000,
        "snapshotHeight": 7837243,
        "version": "1",
        "timestamp": 1637725521
      },
      "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "signature": "0x8a6eb3a9eaceed5a1d3b1026c568d924ce79e887cda1b62cf2ea496e187771648710402f301f01874f0720f4eec327f33c74e687c2e659dd6df039bde72cb489",
      "lastActivityAt": "2021-11-24T03:45:25.619Z",
      "createdAt": "2021-11-24T03:45:25.041Z",
      "updatedAt": "2021-11-24T03:45:25.041Z",
      "cid": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
      "pinHash": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
      "status": "active"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10
}

Fields explanation:

Fields Explanations
_id The primary key of the proposal
cid The proposal unique index
space The name of the space to which the proposal belongs
title The proposal title
content The proposal's detail description
contentType The proposal description content format, currently only "markdown"
choiceType The proposal voting method, single choice or multiple choices
choices A range of options that voters can vote for
startDate Start time for voting
endDate End time for voting
snapshotHeight The voting weight will be calculated based on the snapshot height of the blockchain
weightStrategy Proposal voting weight strategies
data The raw data that was post to create this proposal
address The proposal creator address
signature The signature of the raw post data, signed by proposal creator address
lastActivityAt Last action time of the proposal, including creating, updating, voting or comment actions
createdAt Proposal create time
updatedAt Proposal edit time
pinHash Proposal IPFS storage pin hash
status Proposal status by startDate and endDate, it can be "pending", "active", "closed"

2. Create a proposal

POST /api/[spaceName]/proposals

Request body:

{
  "data": {
    "space": "polkadot",
    "title": "The title",
    "content": "The content",
    "contentType": "markdown",
    "choiceType": "single",
    "choices": [
      "Aye",
      "Nay"
    ],
    "startDate": 1637683200000,
    "endDate": 1638201600000,
    "snapshotHeight": 7838239,
    "version": "1",
    "timestamp": 1637731522
  },
  "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
  "signature": "0x2c662f6676afb63bf156c073275b43d5320ca7e05885360308f21c5b7352076e5b76395d6e98360868ea07bf68f49b735988995640dd16c99e21856563376d8e"
}

Fields explanation:

Fields Explanations
data.space The name of the space to which the proposal belongs
data.title The proposal title
data.content The proposal's detail description
data.contentType The proposal description content format, currently only "markdown"
data.choiceType The proposal voting method, single choice or multiple choices
data.choices A range of options that voters can vote for
data.startDate Start time for voting
data.endDate End time for voting
data.snapshotHeight The voting weight will be calculated based on the snapshot height of the blockchain
data.version The data structure version
data.timestamp Proposal create time
address The proposal creator address
signature The signature of the data message, signed by proposal creator address (data message = JSON.stringify(data))

Response:

{
  "cid": "QmNRBRpQmdQRyDEkUdwWXkrE1wKyA5muXsVTWVG9cfobJh",
}

Fields explanation:

Fields Explanations
cid The proposal unique index

3. Get proposal details

GET /api/[spaceName]/proposal/[id]

Parameters:
  - spaceName: Get proposal for the space (polkadot / kusama / karura / khala)
  - id: The "_id" or "cid" of the proposal

Response

{
  "_id": "619db5558edbaeb5e1620166",
  "space": "polkadot",
  "title": "The proposal title",
  "content": "This is the proposal description",
  "contentType": "markdown",
  "choiceType": "single",
  "choices": [
    "Aye",
    "Nay"
  ],
  "startDate": 1637683200000,
  "endDate": 1638201600000,
  "snapshotHeight": 7837243,
  "weightStrategy": [
    "balance-of",
    "quadratic-balance-of"
  ],
  "data": {
    "space": "polkadot",
    "title": "The proposal title",
    "content": "This is the proposal description",
    "contentType": "markdown",
    "choiceType": "single",
    "choices": [
      "Aye",
      "Nay"
    ],
    "startDate": 1637683200000,
    "endDate": 1638201600000,
    "snapshotHeight": 7837243,
    "version": "1",
    "timestamp": 1637725521
  },
  "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
  "signature": "0x8a6eb3a9eaceed5a1d3b1026c568d924ce79e887cda1b62cf2ea496e187771648710402f301f01874f0720f4eec327f33c74e687c2e659dd6df039bde72cb489",
  "lastActivityAt": "2021-11-24T03:45:25.619Z",
  "createdAt": "2021-11-24T03:45:25.041Z",
  "updatedAt": "2021-11-24T03:45:25.041Z",
  "cid": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
  "pinHash": "QmcPcJ1mLghjKB9BfxUKJcp8kkfGFWqc9MZEf9mWVbfyvE",
  "votesCount": 2,
  "votedWeights": {
    "balanceOf": "22200000000000",
    "quadraticBalanceOf": "666333249958"
  },
  "status": "active"
}

Fields explanation:

Fields Explanations
_id The primary key of the proposal
cid The proposal unique index
space The name of the space to which the proposal belongs
title The proposal title
content The proposal's detail description
contentType The proposal description content format, currently only "markdown"
choiceType The proposal voting method, single choice or multiple choices
choices A range of options that voters can vote for
startDate Start time for voting
endDate End time for voting
snapshotHeight The voting weight will be calculated based on the snapshot height of the blockchain
weightStrategy Proposal voting weight strategies
data The raw data that was post to create this proposal
address The proposal creator address
signature The signature of the raw post data, signed by address
lastActivityAt Last action time of the proposal, including creating, updating, voting or comment actions
createdAt Proposal create time
updatedAt Proposal edit time
pinHash Proposal IPFS storage pin hash
votesCount The current total votes
votedWeights The weight of the current total votes in different strategies
status Proposal status by startDate and endDate, it can be "pending", "active", "closed"

4. Get the list of current votes of a proposal

GET /api/[spaceName]/proposals/[proposalCid]/votes?page=[pageIndex]&page_size=[pageSize]

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - proposalCid: The proposal unique index, which is proposal "cid"
  - pageIndex: The pagination index from 1 to N
  - pageSize: The items count per page

Response

{
  "items": [
    {
      "_id": "619dd7a4bd49f05dc7544802",
      "proposal": "619dccc78edbaeb5e1620167",
      "voter": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "address": "13d8i62igrsVw2bbRBzMtg7fH298n8exz7Y8y1Ty4K5bFuzf",
      "choice": "Aye",
      "cid": "QmcDGZFRSd4eYzXZ5eStrTHZbk7tPvaKvqWVZjWRavyLcV",
      "createdAt": "2021-11-24T06:11:47.908Z",
      "data": {
        "proposalCid": "QmNRBRpQmdQRyDEkUdwWXkrE1wKyA5muXsVTWVG9cfobJh",
        "choice": "Aye",
        "remark": "Sample remark text",
        "version": "1",
        "timestamp": 1637734301
      },
      "pinHash": "QmcDGZFRSd4eYzXZ5eStrTHZbk7tPvaKvqWVZjWRavyLcV",
      "remark": "Sample remark text",
      "signature": "0x6aa2d2497220a1e6a04c50877021757e5547eab7e229a4d0815eaf5b6ba8ef1139c5848742b1a3bf7f0cf8e89d0b54f18c61b9ec5c04e42f683e6e0ad8a96c84",
      "updatedAt": "2021-11-24T06:11:47.908Z",
      "weights": {
        "balanceOf": "11100000000000",
        "quadraticBalanceOf": "333166624979"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10
}

Fields explanation:

Fields Explanations
_id The primary key of the vote
cid The unique index of the vote
proposal The primary key of the associated proposal
voter The voter address. When using proxy voting, it is different from the address of vote creator, otherwise the same
choice The vote choice
remark The remark
data The raw data that was post to create this vote
address The address of vote creator
signature The signature of the raw post data, signed by vote creator address
createdAt Vote create time
pinHash Vote IPFS storage pin hash
weights The weight of the vote in different strategies

5. Get the Voting statistics of a proposal

GET /api/[spaceName]/proposals/[proposalCid]/stats

Parameters:
  - spaceName: Get proposals for the space (polkadot / kusama / karura / khala)
  - proposalCid: The proposal unique index, which is proposal "cid"

Response:

Calculate the sum of weights for each proposal choice separately.

[
  {
    "choice": "Aye",
    "balanceOf": "11100000000000",
    "quadraticBalanceOf": "333166624979"
  },
  {
    "choice": "Nay",
    "balanceOf": "11100000000000",
    "quadraticBalanceOf": "333166624979"
  },
]