Browse Source

Update swagger.yml

feature/sql-semaphore1
jleebee 4 years ago
committed by GitHub
parent
commit
2d85a4d6b9
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 37 deletions
  1. +37
    -37
      api/swagger.yml

+ 37
- 37
api/swagger.yml

@ -17,18 +17,18 @@ info:
All the endpoints that return a list of undefined size use pagination. Unless the opposite is explicitly said. All the endpoints that return a list of undefined size use pagination. Unless the opposite is explicitly said.
In order to use pagination, three query parameters are used: In order to use pagination, three query parameters are used:
* `fromItem`: indicates the first item to be returned. In general, this parameter shouldn't be provided in the first call to the endpoint, and use the `itemId` of the last returned item (+/-) 1, if the order is (ascending/descending). * `fromItem`: indicates the first item to be returned. In general, this parameter shouldn't be provided in the first call to the endpoint, and use the `itemId` of the last returned item (+/-) 1, if the order is (ascending/descending).
* `order`: all paginated items are ordered chronologicaly. However the specific fields to guarantee this order depend on each endpoint. For this purpose, `itemId` is used (itemId follows ascending chronological order except for unforged L1 user transactions). If the parameter is not provided, ascending order will be used by default.
* `order`: all paginated items are ordered chronologically. However, the specific fields to guarantee this order depend on each endpoint. For this purpose, `itemId` is used (itemId follows ascending chronological order except for unforged L1 user transactions). If the parameter is not provided, ascending order will be used by default.
* `limit`: maximum amount of items to include in each response. Default is 20, maximum is 2049. * `limit`: maximum amount of items to include in each response. Default is 20, maximum is 2049.
Responses for those endpoints will always include a `pendingItems` property. This property includes the amount of items that are not fetched yet. This can be used to: Responses for those endpoints will always include a `pendingItems` property. This property includes the amount of items that are not fetched yet. This can be used to:
* Calculate the amount of items that match the filters: `totalItems = length(alreadyFetchedItems) + pendingItems` * Calculate the amount of items that match the filters: `totalItems = length(alreadyFetchedItems) + pendingItems`
* Know when all items have been fetched: `if pendingItems == 0 {/* all items have been fetched */}` * Know when all items have been fetched: `if pendingItems == 0 {/* all items have been fetched */}`
#### Reorgs and safetyness
#### Reorgs and Safety
Since all the items are ordered chronologicaly, there are no safety problems when fetching items in ascending order, except for reorgs (more on this later).
On the other hand, when iterating in descending order, new items will be added at the beginning. This doesn't cause any safety problem, but to get those new items, it's necessary to start queryng without the `fromItem` set to `pagination.lastItem`.
To handle reorgs, the `itemId` can be used since it will change. This is important since other identifiers may be the same but with different content. As an example, if batch 424 gets reorged, it will be deleted, but eventually, a new batch 424 will appear with potentially different content. However these two batches number 424, will have different `itemId`.
Since all the items are ordered chronologically, there are no safety problems when fetching items in ascending order, except for reorgs (more on this later).
On the other hand, when iterating in descending order, new items will be added at the beginning. This doesn't cause any safety problem, but to get those new items, it's necessary to start querying without the `fromItem` set to `pagination.lastItem`.
To handle reorgs, the `itemId` can be used since it will change. This is important since other identifiers may be the same but with different content. As an example, if batch 424 gets reorged, it will be deleted, but eventually, a new batch 424 will appear with potentially different content. However, these two batches number 424, will have different `itemId`.
### Signatures ### Signatures
@ -86,7 +86,7 @@ paths:
- Account - Account
summary: Send an authorization that will allow the coordinator to register accounts associated to an Ethereum address on behalf of the user. summary: Send an authorization that will allow the coordinator to register accounts associated to an Ethereum address on behalf of the user.
description: >- description: >-
Send an authorization to create rollup accounts associated to an Ethereum address. Each account creation (an account can only hold a specific token) is effective once the coordinator forges the corresponding L1CoordinatorTx (which is always of type *account creation*).
Send an authorization to create rollup accounts associated with an Ethereum address. Each account creation (an account can only hold a specific token) is effective once the coordinator forges the corresponding L1CoordinatorTx (which is always of type *account creation*).
operationId: postRegister operationId: postRegister
requestBody: requestBody:
description: Account creation authorization. description: Account creation authorization.
@ -114,7 +114,7 @@ paths:
get: get:
tags: tags:
- Account - Account
summary: Get to know if the coordinator has the ability to create accounts associated to an Ethereum address.
summary: Find out if the coordinator has the ability to create accounts associated with an Ethereum address.
description: >- description: >-
Returns the authorization to perform an account creation with the given Ethereum address on behalf of the Ethereum address holder. Returns the authorization to perform an account creation with the given Ethereum address on behalf of the Ethereum address holder.
operationId: getAccountCreationAuthorization operationId: getAccountCreationAuthorization
@ -155,7 +155,7 @@ paths:
tags: tags:
- Account - Account
summary: Get accounts balances and other associated information. summary: Get accounts balances and other associated information.
description: Get accounts balances and other associated information.
description: Get account balances and other associated information.
operationId: getAccounts operationId: getAccounts
parameters: parameters:
- name: hezEthereumAddress - name: hezEthereumAddress
@ -282,7 +282,7 @@ paths:
$ref: '#/components/schemas/TokenId' $ref: '#/components/schemas/TokenId'
- name: hezEthereumAddress - name: hezEthereumAddress
in: query in: query
description: Get exits associated to a Ethereum address. Incompatible with query `BJJ` and `accountIndex`.
description: Get exits associated to an Ethereum address. Incompatible with query `BJJ` and `accountIndex`.
required: false required: false
schema: schema:
$ref: '#/components/schemas/HezEthereumAddress' $ref: '#/components/schemas/HezEthereumAddress'
@ -444,7 +444,7 @@ paths:
- Transaction - Transaction
summary: Get details and status of a transaction that is in the pool. summary: Get details and status of a transaction that is in the pool.
description: >- description: >-
Get transaction from the pool by its id. This endpoint is specially useful for tracking the status of a transaction that may not be forged yet.
Get transaction from the pool by its ID. This endpoint is specially useful for tracking the status of a transaction that may not be forged yet.
Only transactions from the pool will be returned. Only transactions from the pool will be returned.
Note that the transaction pool is different for each coordinator and therefore only a coordinator that has received a specific transaction Note that the transaction pool is different for each coordinator and therefore only a coordinator that has received a specific transaction
will be able to provide information about that transaction. will be able to provide information about that transaction.
@ -501,12 +501,12 @@ paths:
- name: hezEthereumAddress - name: hezEthereumAddress
in: query in: query
required: false required: false
description: Only get transactions sent from or to an account associated to an Ethereum address Incompatible with the queries `BJJ` and `accountIndex`.
description: Only get transactions sent from or to an account associated with an Ethereum address Incompatible with the queries `BJJ` and `accountIndex`.
schema: schema:
$ref: '#/components/schemas/HezEthereumAddress' $ref: '#/components/schemas/HezEthereumAddress'
- name: BJJ - name: BJJ
in: query in: query
description: Only get transactions associated to a BabyJubJub public key. Incompatible with the queries `hezEthereumAddress` and `accountIndex`.
description: Only get transactions associated with a BabyJubJub public key. Incompatible with the queries `hezEthereumAddress` and `accountIndex`.
required: false required: false
schema: schema:
$ref: '#/components/schemas/BJJ' $ref: '#/components/schemas/BJJ'
@ -583,7 +583,7 @@ paths:
- Transaction - Transaction
summary: Get details and status of a historical transaction. summary: Get details and status of a historical transaction.
description: >- description: >-
Get transaction by its id. This endpoint will return all the different types of transactions except those that are still in the pool of any coordinator.
Get transaction by its ID. This endpoint will return all the different types of transactions except those that are still in the pool of any coordinator.
operationId: getHistoryTx operationId: getHistoryTx
parameters: parameters:
- name: id - name: id
@ -1022,8 +1022,8 @@ paths:
get: get:
tags: tags:
- Hermez status - Hermez status
summary: Get information of the supported tokens in the Hermez network.
description: Get information of the supported tokens in the Hermez network.
summary: Get information of the supported tokens in the Hermez Network.
description: Get information of the supported tokens in the Hermez Network.
operationId: getTokens operationId: getTokens
parameters: parameters:
- name: ids - name: ids
@ -1101,8 +1101,8 @@ paths:
get: get:
tags: tags:
- Hermez status - Hermez status
summary: Get information of a token supported by Hermez network.
description: Get information of a token supported by Hermez network.
summary: Get information of a token supported by Hermez Network.
description: Get information of a token supported by Hermez Network.
operationId: getToken operationId: getToken
parameters: parameters:
- name: id - name: id
@ -1253,7 +1253,7 @@ components:
nullable: true nullable: true
toHezEthereumAddress: toHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network. If this is provided, toAccountIndex and toBjj must be null."
description: "Address of an Etherum account linked to the Hermez Network. If this is provided, toAccountIndex and toBjj must be null."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true nullable: true
@ -1261,7 +1261,7 @@ components:
type: string type: string
description: >- description: >-
BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes. BabyJubJub public key, encoded as base64 URL (RFC 4648), which result in 33 bytes. The padding byte is replaced by a sum of the encoded bytes.
If this is prvided, toAccountIndex must be null and toHezEthereumAddress must be hez:0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
If this is provided, toAccountIndex must be null and toHezEthereumAddress must be hez:0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
pattern: "^hez:[A-Za-z0-9_-]{44}$" pattern: "^hez:[A-Za-z0-9_-]{44}$"
example: null example: null
nullable: true nullable: true
@ -1354,7 +1354,7 @@ components:
$ref: '#/components/schemas/AccountIndex' $ref: '#/components/schemas/AccountIndex'
fromHezEthereumAddress: fromHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true nullable: true
@ -1373,7 +1373,7 @@ components:
nullable: true nullable: true
toHezEthereumAddress: toHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: null example: null
nullable: true nullable: true
@ -1405,7 +1405,7 @@ components:
format: date-time format: date-time
batchNum: batchNum:
type: integer type: integer
description: Identifier of a batch. Every new forged batch increments by one the batchNum, starting at 0.
description: Identifier of a batch. Every new forged batch increases by one the batchNum, starting at 0.
minimum: 0 minimum: 0
maximum: 4294967295 maximum: 4294967295
nullable: true nullable: true
@ -1426,7 +1426,7 @@ components:
example: null example: null
requestToHezEthereumAddress: requestToHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
nullable: true nullable: true
example: null example: null
@ -1532,7 +1532,7 @@ components:
example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
HezEthereumAddress: HezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
BJJ: BJJ:
@ -1662,7 +1662,7 @@ components:
- signature - signature
HistoryTransaction: HistoryTransaction:
type: object type: object
description: Transaction of the Hermez network
description: Transaction of the Hermez Network
properties: properties:
L1orL2: L1orL2:
type: string type: string
@ -1686,7 +1686,7 @@ components:
nullable: true nullable: true
fromHezEthereumAddress: fromHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true nullable: true
@ -1702,7 +1702,7 @@ components:
- example: "hez:DAI:672" - example: "hez:DAI:672"
toHezEthereumAddress: toHezEthereumAddress:
type: string type: string
description: "Address of an Etherum account linked to the Hermez network."
description: "Address of an Etherum account linked to the Hermez Network."
pattern: "^hez:0x[a-fA-F0-9]{40}$" pattern: "^hez:0x[a-fA-F0-9]{40}$"
example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a" example: "hez:0xaa942cfcd25ad4d90a62358b0dd84f33b398262a"
nullable: true nullable: true
@ -2247,12 +2247,12 @@ components:
example: 1.3 example: 1.3
createAccountInternal: createAccountInternal:
type: number type: number
description: Recommended fee if the destination account of the transaction doesn't exist, but the coordinator has the ability to create a valid account associated to a BJJ public key controlled by the receiver. Note that these kind of accounts are not associated to an Ethereum address and therefore can only operate in L2.
description: Recommended fee if the destination account of the transaction doesn't exist, but the coordinator has the ability to create a valid account associated to a BJJ public key controlled by the receiver. Note that these kind of accounts are not associated with an Ethereum address and therefore can only operate in L2.
minimum: 0 minimum: 0
example: 0.5 example: 0.5
Token: Token:
type: object type: object
description: Hermez network compatible and registered token.
description: Hermez Network compatible and registered token.
properties: properties:
id: id:
$ref: '#/components/schemas/TokenId' $ref: '#/components/schemas/TokenId'
@ -2278,7 +2278,7 @@ components:
ethereumBlockNum: ethereumBlockNum:
allOf: allOf:
- $ref: '#/components/schemas/EthBlockNum' - $ref: '#/components/schemas/EthBlockNum'
- description: Ethereum block number in which the token was added to the Hermez network.
- description: Ethereum block number in which the token was added to the Hermez Network.
- example: 539847538 - example: 539847538
USD: USD:
type: number type: number
@ -2711,7 +2711,7 @@ components:
example: 2 example: 2
openAuctionSlots: openAuctionSlots:
type: integer type: integer
description: How many days in advance are auctions opened.
description: Amount of days in advance are auctions opened.
defaultSlotSetBid: defaultSlotSetBid:
type: array type: array
description: "Initial minimal bid for each auction. Expressed as an array of 6 values. To calculate which value corresponds to each slot: `initialMinimalBidding[slotNum%6]`." description: "Initial minimal bid for each auction. Expressed as an array of 6 values. To calculate which value corresponds to each slot: `initialMinimalBidding[slotNum%6]`."
@ -2729,7 +2729,7 @@ components:
- example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430" - example: "0x887dc4262BCDbf85190C01c996b4C06a461d2430"
allocationRatio: allocationRatio:
type: array type: array
description: Percentage in which fees will be splitted between donations, governance and burning. The sum of the tree values should be 100.
description: Percentage in which fees will be split between donations, governance, and burning. The sum of the tree values should be 100.
items: items:
type: integer type: integer
example: [80,10,10] example: [80,10,10]
@ -2753,7 +2753,7 @@ components:
$ref: '#/components/schemas/EthBlockNum' $ref: '#/components/schemas/EthBlockNum'
forgeL1L2BatchTimeout: forgeL1L2BatchTimeout:
type: integer type: integer
description: Max ethereum blocks after the last L1-L2-batch, when exceeds the timeout only L1-L2-batch are allowed.
description: Max Ethereum blocks after the last L1-L2-batch, when exceeds the timeout only L1-L2-batch are allowed.
example: 5 example: 5
feeAddToken: feeAddToken:
type: integer type: integer
@ -2817,12 +2817,12 @@ components:
emergencyCouncilAddress: emergencyCouncilAddress:
allOf: allOf:
- $ref: '#/components/schemas/EthereumAddress' - $ref: '#/components/schemas/EthereumAddress'
- description: Ethereum Address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
- description: Ethereum address that can claim the funds in an emergency when the maximum emergency mode time is exceeded.
- example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430" - example: "0x557dc4262BCDbf85190C01c996b4C06a461d2430"
withdrawalDelay: withdrawalDelay:
allOf: allOf:
- $ref: '#/components/schemas/EthBlockNum' - $ref: '#/components/schemas/EthBlockNum'
- description: The time that anyone needs to wait until a withdrawal of the funds is allowed, in seconds.
- description: The time that everyone needs to wait until a withdrawal of the funds is allowed, in seconds.
- example: 539573849 - example: 539573849
emergencyModeStartingTime: emergencyModeStartingTime:
type: integer type: integer
@ -2882,7 +2882,7 @@ components:
example: 15 example: 15
Config: Config:
type: object type: object
description: Configuration parameters of the different smart contracts that power the Hermez network.
description: Configuration parameters of the different smart contracts that power the Hermez Network.
properties: properties:
hermez: hermez:
type: object type: object
@ -3098,4 +3098,4 @@ components:
allOf: allOf:
- $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/Error'
- example: - example:
message: Database error.
message: Database error.

Loading…
Cancel
Save