Skip to content

Commit a7697ab

Browse files
ncyingncying
authored
Merge pull request #302 from virtualeconomy/Riemann
VSYS API Update
2 parents 86b9937 + 0b41744 commit a7697ab

32 files changed

+286
-162
lines changed

‎src/main/scala/vsys/api/http/BlocksApiRoute.scala

+33-14
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
package vsys.api.http
22

33
import javax.ws.rs.Path
4-
54
import akka.http.scaladsl.marshalling.ToResponseMarshallable
65
import akka.http.scaladsl.server.Route
76
import io.netty.channel.group.ChannelGroup
@@ -13,7 +12,6 @@ import vsys.blockchain.state.ByteStr
1312
import vsys.blockchain.transaction.TransactionParser
1413
import vsys.network._
1514
import vsys.settings.{CheckpointsSettings, RestAPISettings}
16-
1715
import scala.concurrent.ExecutionContext.Implicits.global
1816
import scala.concurrent.Future
1917

@@ -31,7 +29,10 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
3129
}
3230

3331
@Path("/address/{address}/{from}/{to}")
34-
@ApiOperation(value = "Address", notes = "Get list of blocks generated by specified address", httpMethod = "GET")
32+
@ApiOperation(value = "Address", notes = "Get a block list generated by a specified `address` and a block height range (`from`/`to`)", httpMethod = "GET")
33+
@ApiResponses(Array(
34+
new ApiResponse(code = 200, message = "Json response of the block list or error")
35+
))
3536
@ApiImplicitParams(Array(
3637
new ApiImplicitParam(name = "from", value = "Start block height", required = true, dataType = "integer", paramType = "path"),
3738
new ApiImplicitParam(name = "to", value = "End block height", required = true, dataType = "integer", paramType = "path"),
@@ -52,10 +53,13 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
5253
}
5354

5455
@Path("/child/{signature}")
55-
@ApiOperation(value = "Child", notes = "Get children of specified block", httpMethod = "GET")
56+
@ApiOperation(value = "Child", notes = "Get children of a specified block by the base58-encoded `signature`", httpMethod = "GET")
5657
@ApiImplicitParams(Array(
5758
new ApiImplicitParam(name = "signature", value = "Base58-encoded signature", required = true, dataType = "string", paramType = "path")
5859
))
60+
@ApiResponses(Array(
61+
new ApiResponse(code = 200, message = "Json response of the child block information or error")
62+
))
5963
def child: Route = (path("child" / Segment) & get) { encodedSignature =>
6064
withBlock(history, encodedSignature) { block =>
6165
complete(history.child(block).map(_.json + ("transaction count" -> Json.toJson(block.transactionData.length))).getOrElse[JsObject](
@@ -65,7 +69,7 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
6569

6670
@Path("/delay/{signature}/{blockNum}")
6771
@ApiOperation(value = "Average delay",
68-
notes = "Average delay in milliseconds between last `blockNum` blocks starting from block with `signature`", httpMethod = "GET")
72+
notes = "Get the average delay in milliseconds between last `blockNum` blocks starting from block with `signature`", httpMethod = "GET", response = classOf[Long])
6973
@ApiImplicitParams(Array(
7074
new ApiImplicitParam(name = "signature", value = "Base58-encoded signature", required = true, dataType = "string", paramType = "path"),
7175
new ApiImplicitParam(name = "blockNum", value = "Number of blocks to count delay", required = true, dataType = "string", paramType = "path")
@@ -78,7 +82,7 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
7882
}
7983

8084
@Path("/height/{signature}")
81-
@ApiOperation(value = "Height", notes = "Get height of a block by its Base58-encoded signature", httpMethod = "GET")
85+
@ApiOperation(value = "Height", notes = "Get the **block height** by its Base58-encoded `signature`", httpMethod = "GET", response = classOf[Int])
8286
@ApiImplicitParams(Array(
8387
new ApiImplicitParam(name = "signature", value = "Base58-encoded signature", required = true, dataType = "string", paramType = "path")
8488
))
@@ -95,13 +99,16 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
9599
}
96100

97101
@Path("/height")
98-
@ApiOperation(value = "Height", notes = "Get blockchain height", httpMethod = "GET")
102+
@ApiOperation(value = "Height", notes = "Get blockchain height", httpMethod = "GET", response=classOf[Int])
99103
def height: Route = (path("height") & get) {
100104
complete(Json.obj("height" -> history.height()))
101105
}
102106

103107
@Path("/at/{height}")
104-
@ApiOperation(value = "At", notes = "Get block at specified height", httpMethod = "GET")
108+
@ApiOperation(value = "At", notes = "Get block at specified `height`", httpMethod = "GET")
109+
@ApiResponses(Array(
110+
new ApiResponse(code = 200, message = "Json response of a block details at a specified height or error")
111+
))
105112
@ApiImplicitParams(Array(
106113
new ApiImplicitParam(name = "height", value = "Block height", required = true, dataType = "integer", paramType = "path")
107114
))
@@ -113,7 +120,10 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
113120
}
114121

115122
@Path("/seq/{from}/{to}")
116-
@ApiOperation(value = "Seq", notes = "Get block at specified heights", httpMethod = "GET")
123+
@ApiOperation(value = "Seq", notes = "Get block at the specified height range (`from`/`to`)", httpMethod = "GET")
124+
@ApiResponses(Array(
125+
new ApiResponse(code = 200, message = "Json response of the block list or error")
126+
))
117127
@ApiImplicitParams(Array(
118128
new ApiImplicitParam(name = "from", value = "Start block height", required = true, dataType = "integer", paramType = "path"),
119129
new ApiImplicitParam(name = "to", value = "End block height", required = true, dataType = "integer", paramType = "path")
@@ -130,21 +140,30 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
130140

131141

132142
@Path("/last")
133-
@ApiOperation(value = "Last", notes = "Get last block data", httpMethod = "GET")
143+
@ApiOperation(value = "Last", notes = "Get the **last block** data", httpMethod = "GET")
144+
@ApiResponses(Array(
145+
new ApiResponse(code = 200, message = "Json response of the last block information or error")
146+
))
134147
def last: Route = (path("last") & get) {
135148
val height = history.height()
136149
val lastBlock = history.blockAt(height).get
137150
complete(lastBlock.json + ("height" -> Json.toJson(height)) + ("transaction count" -> Json.toJson(lastBlock.transactionData.length)))
138151
}
139152

140153
@Path("/first")
141-
@ApiOperation(value = "First", notes = "Get genesis block data", httpMethod = "GET")
154+
@ApiOperation(value = "First", notes = "Get the **genesis block** data", httpMethod = "GET")
155+
@ApiResponses(Array(
156+
new ApiResponse(code = 200, message = "Json response of the first block details or error")
157+
))
142158
def first: Route = (path("first") & get) {
143159
complete(history.genesis.json + ("height" -> Json.toJson(1)) + ("transaction count" -> Json.toJson(history.genesis.transactionData.length)))
144160
}
145161

146162
@Path("/signature/{signature}")
147-
@ApiOperation(value = "Signature", notes = "Get block by a specified Base58-encoded signature", httpMethod = "GET")
163+
@ApiOperation(value = "Signature", notes = "Get block by a specified Base58-encoded `signature`", httpMethod = "GET")
164+
@ApiResponses(Array(
165+
new ApiResponse(code = 200, message = "Json response of the block details or error")
166+
))
148167
@ApiImplicitParams(Array(
149168
new ApiImplicitParam(name = "signature", value = "Base58-encoded signature", required = true, dataType = "string", paramType = "path")
150169
))
@@ -159,13 +178,13 @@ case class BlocksApiRoute(settings: RestAPISettings, checkpointsSettings: Checkp
159178
}
160179

161180
@Path("/checkpoint")
162-
@ApiOperation(value = "Checkpoint", notes = "Broadcast checkpoint of blocks", httpMethod = "POST")
181+
@ApiOperation(value = "Checkpoint", notes = "Broadcast the checkpoint of blocks", httpMethod = "POST")
163182
@ApiImplicitParams(Array(
164183
new ApiImplicitParam(name = "message", value = "Checkpoint message", required = true, paramType = "body",
165184
dataType = "vsys.network.Checkpoint")
166185
))
167186
@ApiResponses(Array(
168-
new ApiResponse(code = 200, message = "Json with response or error")
187+
new ApiResponse(code = 200, message = "Successful Operation")
169188
))
170189
def checkpoint: Route = (path("checkpoint") & post) {
171190
json[Checkpoint] { checkpoint =>

‎src/main/scala/vsys/api/http/NodeApiRoute.scala

+9-3
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ case class NodeApiRoute(settings: RestAPISettings,
2424
}
2525

2626
@Path("/version")
27-
@ApiOperation(value = "Version", notes = "Get VSYS node version", httpMethod = "GET")
27+
@ApiOperation(value = "Version", notes = "Get VSYS node version", httpMethod = "GET", response = classOf[String])
2828
@ApiResponses(Array(
29-
new ApiResponse(code = 200, message = "Json VSYS node version")
29+
new ApiResponse(code = 200, message = "Json response of VSYS node version")
3030
))
3131
def version: Route = (get & path("version")) {
3232
complete(Json.obj("version" -> Constants.AgentName))
@@ -35,14 +35,20 @@ case class NodeApiRoute(settings: RestAPISettings,
3535
@Path("/stop")
3636
@ApiOperation(value = "Stop", notes = "Stop the node", httpMethod = "POST",
3737
authorizations = Array(new Authorization("api_key")))
38+
@ApiResponses(Array(
39+
new ApiResponse(code = 200, message = "Successful Operation")
40+
))
3841
def stop: Route = (post & path("stop") & withAuth) {
3942
log.info("Request to stop application")
4043
application.shutdown()
4144
complete(Json.obj("stopped" -> true))
4245
}
4346

4447
@Path("/status")
45-
@ApiOperation(value = "Status", notes = "Get status of the running core", httpMethod = "GET")
48+
@ApiOperation(value = "Status", notes = "Get **status** of the running core", httpMethod = "GET")
49+
@ApiResponses(Array(
50+
new ApiResponse(code = 200, message = "Json response of the node status or error")
51+
))
4652
def status: Route = (get & path("status")) {
4753
val lastUpdated = history.lastBlock.get.timestamp
4854
complete(

‎src/main/scala/vsys/api/http/PeersApiRoute.scala

+14-12
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ case class PeersApiRoute(
2929
}
3030

3131
@Path("/all")
32-
@ApiOperation(value = "Peer list", notes = "Peer list", httpMethod = "GET")
32+
@ApiOperation(value = "Peer list", notes = "Get the peer list", httpMethod = "GET")
3333
@ApiResponses(Array(
34-
new ApiResponse(code = 200, message = "Json with peer list or error")
34+
new ApiResponse(code = 200, message = "Json response of a peer list or error")
3535
))
3636
def allPeers: Route = (path("all") & get) {
3737
complete(Json.obj("peers" ->
@@ -44,9 +44,9 @@ case class PeersApiRoute(
4444
}
4545

4646
@Path("/connected")
47-
@ApiOperation(value = "Connected peers list", notes = "Connected peers list", httpMethod = "GET")
47+
@ApiOperation(value = "Connected peers list", notes = "Get the connected peers list", httpMethod = "GET")
4848
@ApiResponses(Array(
49-
new ApiResponse(code = 200, message = "Json with connected peers or error")
49+
new ApiResponse(code = 200, message = "Json response of a connected peers list or error")
5050
))
5151
def connectedPeers: Route = (path("connected") & get) {
5252
val peers = establishedConnections.values().stream().map[JsValue](pi => Json.obj(
@@ -64,14 +64,16 @@ case class PeersApiRoute(
6464
@Path("/connect")
6565
@ApiOperation(value = "Connect to peer", notes = "Connect to peer", httpMethod = "POST",
6666
authorizations = Array(new Authorization("api_key")))
67+
@ApiResponses(Array(
68+
new ApiResponse(code = 200, message = "Successful Operation")
69+
))
6770
@ApiImplicitParams(Array(
6871
new ApiImplicitParam(
6972
name = "body",
70-
value = "Json with data",
73+
value = "Peer host settings",
7174
required = true,
7275
paramType = "body",
73-
dataType = "string",
74-
defaultValue = "{\n\t\"host\":\"127.0.0.1\",\n\t\"port\":\"9084\"\n}"
76+
dataType = "vsys.network.PeerNetworkConnection",
7577
)
7678
))
7779
def connect: Route = (path("connect") & post & withAuth) {
@@ -84,10 +86,10 @@ case class PeersApiRoute(
8486
}
8587

8688
@Path("/blacklisted")
87-
@ApiOperation(value = "Blacklisted peers list", notes = "Blacklisted peers list", httpMethod = "GET")
89+
@ApiOperation(value = "Blacklisted peers list", notes = "Get the blacklisted peers list", httpMethod = "GET")
8890
@ApiResponses(
8991
Array(
90-
new ApiResponse(code = 200, message = "Json with blacklisted peers or error")
92+
new ApiResponse(code = 200, message = "Json response of the blacklisted peers or error")
9193
))
9294
def blacklistedPeers: Route = (path("blacklisted") & get) {
9395
complete(
@@ -99,10 +101,10 @@ case class PeersApiRoute(
99101
}
100102

101103
@Path("/suspended")
102-
@ApiOperation(value = "Suspended peers list", notes = "Suspended peers list", httpMethod = "GET")
104+
@ApiOperation(value = "Suspended peers list", notes = "Get the suspended peers list", httpMethod = "GET")
103105
@ApiResponses(
104106
Array(
105-
new ApiResponse(code = 200, message = "JSON with suspended peers or error")
107+
new ApiResponse(code = 200, message = "JSON response of a suspended peer list or error")
106108
))
107109
def suspendedPeers: Route = (path("suspended") & get) {
108110
complete(
@@ -115,7 +117,7 @@ case class PeersApiRoute(
115117
authorizations = Array(new Authorization("api_key")))
116118
@ApiResponses(
117119
Array(
118-
new ApiResponse(code = 200, message = "200")
120+
new ApiResponse(code = 200, message = "Successful Operation")
119121
))
120122
def clearBlacklist: Route = (path("clearblacklist") & post & withAuth) {
121123
peerDatabase.clearBlacklist()

‎src/main/scala/vsys/api/http/TransactionsApiRoute.scala

+17-5
Original file line numberDiff line numberDiff line change
@@ -162,8 +162,11 @@ case class TransactionsApiRoute(
162162
}
163163

164164
@Path("/activeLeaseList/{address}")
165-
@ApiOperation(value = "Address", notes = "Get list of active lease transactions", httpMethod = "GET",
165+
@ApiOperation(value = "Address", notes = "Get a list of **active lease transactions** by a specified `address`", httpMethod = "GET",
166166
authorizations = Array(new Authorization("api_key")))
167+
@ApiResponses(Array(
168+
new ApiResponse(code = 200, message = "Json response with a list of active lease transactions or error")
169+
))
167170
@ApiImplicitParams(Array(
168171
new ApiImplicitParam(name = "address", value = "Wallet address ", required = true, dataType = "string", paramType = "path"),
169172
))
@@ -186,7 +189,10 @@ case class TransactionsApiRoute(
186189
}
187190

188191
@Path("/info/{id}")
189-
@ApiOperation(value = "Info", notes = "Get transaction info", httpMethod = "GET")
192+
@ApiOperation(value = "Info", notes = "Get transaction info by a specified transaction `id`", httpMethod = "GET")
193+
@ApiResponses(Array(
194+
new ApiResponse(code = 200, message = "Json response of transaction info or error")
195+
))
190196
@ApiImplicitParams(Array(
191197
new ApiImplicitParam(name = "id", value = "transaction id ", required = true, dataType = "string", paramType = "path")
192198
))
@@ -209,21 +215,27 @@ case class TransactionsApiRoute(
209215
}
210216

211217
@Path("/unconfirmed")
212-
@ApiOperation(value = "Unconfirmed", notes = "Get list of unconfirmed transactions", httpMethod = "GET")
218+
@ApiResponses(Array(
219+
new ApiResponse(code = 200, message = "Json response of the unconfirmed transactions list or error")
220+
))
221+
@ApiOperation(value = "Unconfirmed", notes = "Get a list of unconfirmed transactions", httpMethod = "GET")
213222
def unconfirmed: Route = (pathPrefix("unconfirmed") & get) {
214223
pathEndOrSingleSlash {
215224
complete(JsArray(utxPool.all().map(txToExtendedJson)))
216225
} ~ utxSize ~ utxTransactionInfo
217226
}
218227

219228
@Path("/unconfirmed/size")
220-
@ApiOperation(value = "Size of UTX pool", notes = "Get number of unconfirmed transactions in the UTX pool", httpMethod = "GET")
229+
@ApiOperation(value = "Size of UTX pool", notes = "Get the number of transactions in the unconfirmed transactions(UTX) pool", httpMethod = "GET", response = classOf[Int])
221230
def utxSize: Route = (pathPrefix("size") & get) {
222231
complete(Json.obj("size" -> JsNumber(utxPool.size)))
223232
}
224233

225234
@Path("/unconfirmed/info/{id}")
226-
@ApiOperation(value = "Transaction Info", notes = "Get transaction that is in the UTX", httpMethod = "GET")
235+
@ApiOperation(value = "Transaction Info", notes = "Get the **unconfirmed transaction** by a specified transaction `id`", httpMethod = "GET")
236+
@ApiResponses(Array(
237+
new ApiResponse(code = 200, message = "Json response of the unconfirmed transaction info or error")
238+
))
227239
@ApiImplicitParams(Array(
228240
new ApiImplicitParam(name = "id", value = "Transaction id ", required = true, dataType = "string", paramType = "path")
229241
))

‎src/main/scala/vsys/api/http/UtilsApiRoute.scala

+13-11
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,10 @@ case class UtilsApiRoute(timeService: Time, settings: RestAPISettings) extends A
2828
}
2929

3030
@Path("/time")
31-
@ApiOperation(value = "Time", notes = "Current Node time (UTC)", httpMethod = "GET")
31+
@ApiOperation(value = "Time", notes = "Get the Current Node time (UTC)", httpMethod = "GET")
3232
@ApiResponses(
3333
Array(
34-
new ApiResponse(code = 200, message = "Json with time or error")
34+
new ApiResponse(code = 200, message = "Json response of the current node time or error")
3535
))
3636
def time: Route = (path("time") & get) {
3737
val t = System.currentTimeMillis()*1000000L + System.nanoTime()%1000000L
@@ -41,30 +41,32 @@ case class UtilsApiRoute(timeService: Time, settings: RestAPISettings) extends A
4141
@Path("/seed")
4242
@ApiOperation(value = "Seed", notes = "Generate random seed", httpMethod = "GET")
4343
@ApiResponses(Array(
44-
new ApiResponse(code = 200, message = "Json with peer list or error")
44+
new ApiResponse(code = 200, message = "Json response of a random seed or error")
4545
))
4646
def seedRoute: Route = (path("seed") & get) {
4747
complete(seed(DefaultSeedSize))
4848
}
4949

5050
@Path("/seed/{length}")
51-
@ApiOperation(value = "Seed of specified length", notes = "Generate random seed of specified length", httpMethod = "GET")
51+
@ApiOperation(value = "Seed of specified length", notes = "Generate random seed of specified `length`", httpMethod = "GET")
5252
@ApiImplicitParams(Array(
5353
new ApiImplicitParam(name = "length", value = "Seed length ", required = true, dataType = "integer", paramType = "path")
5454
))
55-
@ApiResponse(code = 200, message = "Json with error message")
55+
@ApiResponses(Array(
56+
new ApiResponse(code = 200, message = "Json response of a random seed or error")
57+
))
5658
def length: Route = (path("seed" / IntNumber) & get) { length =>
5759
if (length <= MaxSeedSize) complete(seed(length))
5860
else complete(TooBigArrayAllocation)
5961
}
6062

6163
@Path("/hash/secure")
62-
@ApiOperation(value = "Hash", notes = "Return SecureCryptographicHash of specified message", httpMethod = "POST")
64+
@ApiOperation(value = "Hash", notes = "Return a hash(SecureCryptographicHash) of a specified `message`", httpMethod = "POST")
6365
@ApiImplicitParams(Array(
6466
new ApiImplicitParam(name = "message", value = "Message to hash", required = true, paramType = "body", dataType = "string")
6567
))
6668
@ApiResponses(Array(
67-
new ApiResponse(code = 200, message = "Json with error or json like {\"message\": \"your message\",\"hash\": \"your message hash\"}")
69+
new ApiResponse(code = 200, message = "Successful Operation")
6870
))
6971
def hashSecure: Route = (path("hash" / "secure") & post) {
7072
entity(as[String]) { message =>
@@ -73,12 +75,12 @@ case class UtilsApiRoute(timeService: Time, settings: RestAPISettings) extends A
7375
}
7476

7577
@Path("/hash/fast")
76-
@ApiOperation(value = "Hash", notes = "Return FastCryptographicHash of specified message", httpMethod = "POST")
78+
@ApiOperation(value = "Hash", notes = "Return a hash(FastCryptographicHash) of a specified `message`", httpMethod = "POST")
7779
@ApiImplicitParams(Array(
7880
new ApiImplicitParam(name = "message", value = "Message to hash", required = true, paramType = "body", dataType = "string")
7981
))
8082
@ApiResponses(Array(
81-
new ApiResponse(code = 200, message = "Json with error or json like {\"message\": \"your message\",\"hash\": \"your message hash\"}")
83+
new ApiResponse(code = 200, message = "Successful Operation")
8284
))
8385
def hashFast: Route = (path("hash" / "fast") & post) {
8486
entity(as[String]) { message =>
@@ -88,13 +90,13 @@ case class UtilsApiRoute(timeService: Time, settings: RestAPISettings) extends A
8890

8991

9092
@Path("/sign/{privateKey}")
91-
@ApiOperation(value = "Hash", notes = "Return FastCryptographicHash of specified message", httpMethod = "POST")
93+
@ApiOperation(value = "Hash", notes = "Return a hash(FastCryptographicHash) of a specified message with the `privateKey`", httpMethod = "POST")
9294
@ApiImplicitParams(Array(
9395
new ApiImplicitParam(name = "privateKey", value = "privateKey", required = true, paramType = "path", dataType = "string"),
9496
new ApiImplicitParam(name = "message", value = "Message to hash", required = true, paramType = "body", dataType = "string")
9597
))
9698
@ApiResponses(Array(
97-
new ApiResponse(code = 200, message = "Json with error or json like {\"message\": \"your message\",\"hash\": \"your message hash\"}")
99+
new ApiResponse(code = 200, message = "Successful Operation")
98100
))
99101
def sign: Route = (path("sign" / Segment) & post) {pk =>
100102
entity(as[String]) { message =>

0 commit comments

Comments
 (0)