OpenAPI specification for catapult-rest
Home Page: https://nemtech.github.io/api.html
License: Apache License 2.0
OpenAPI specification for catapult-rest.
symbol-openapi repository.git clone https://github.com/nemtech/symbol-openapi.git
swagger-cli globally.npm install -g @apidevtools/swagger-cli
Compile the specification.
The generated output is saved under _build directory.
npm run build
Check if the specification is valid.
npm run test
Before contributing please read this.
Copyright (c) 2018-present NEM Licensed under the Apache License 2.0
Document new pagination approach symbol/catapult-rest#172 based on the conversations with the REST and SDK teams:
Implemented in: symbol/catapult-rest@68b26e6
/node/peers
Example output:
[
{
"version": 0,
"publicKey": "6767654342D851850ADD01F2A739F8D0798976543216A9D704A189AA4565EE3F",
"networkGenerationHash": "292A26631A2F5D988D726594AD018B2ECCD69F61C8F0060A3284255392169259",
"roles": 1,
"port": 7900,
"networkIdentifier": 152,
"host": "peer-node-0",
"friendlyName": "peer-node-0"
},
{
"version": 0,
"publicKey": "189AA4565EE3F6767654342D851850ADD01F2A739F8D0798976543216A9D704A",
"networkGenerationHash": "AA45467892F5D988D726594AD018B2ECCD69F61C8F0060A32842555654B45C4A",
"roles": 1,
"port": 7900,
"networkIdentifier": 152,
"host": "peer-node-1",
"friendlyName": "peer-node-1"
}
]
Notice that the output is just an array of nodeInfo items, you may be able to reuse an existing openApi DTO
For Mosaic Restrictions, OpenAPI uses "AddressMosaic...DTO" and "GlobalMosaic...DTO"
but Catbuffer uses "MosaicAddress...Builder" and "MosaicGlobal...Builder".
harvestNetworkPercentage
harvestNetworkFeeSinkPublicKey
New errors were added for the new transaction added in 0.9.5.1. the transaction status type enum needs to be updated. Below is one example.
catapult_server0001.log:2020-05-19 23:38:59.580589 0x00007fc445ffb700: (chain::UtUpdater.cpp@160) dropping transaction 61D3415802FEE63086E95D0260A9B000CB6DA594A15FA65BB535DFD36847649F: Failure_Core_Link_Already_Exists
catapult_server0001.log:2020-05-19 23:38:59.586438 0x00007fc445ffb700: (subscribers::SubscriptionManager.cpp@101) rejected tx 61D3415802FEE63086E95D0260A9B000CB6DA594A15FA65BB535DFD36847649F due to result Failure_Core_Link_Already_Exists (deadline 16508338905)
The project https://github.com/NEMStudios/nem2-open-api-generator generates maven and npm packages for the Java and TS SDKs.
The version of the generated artifacts must match the version of the Open API spec. You can tell exactly what version of the open API of the clients are generated from, and by extension, the Open API version the SDKs support.
Maven supports multiple number versions but NPM complains if there are more than 2 dots in a version (if there are just numbers).
The current version of the spec is 0.7.20.6. https://github.com/nemtech/nem2-openapi/blob/master/spec/info.yml#L1
We need to touch the generated NPM package version calling it something different like 0.7.20-beta.6
https://www.npmjs.com/package/nem2-sdk-openapi-typescript-node-client
Could it be possible to use a simple 3 numbers version in the spec like 0.7.21 and update the minor version with every merged change?
CC: @dgarcia360 @rg911
Hi @dgarcia360,
I'm working on the Persistent Harvesting Delegation Unlocking feature for the java SDK.
https://nem.atlassian.net/browse/JS-15
I've noticed that the message type is missing. Could it be added?
254: Persistent harvesting delegation.
Describe the path and response of node/health symbol/catapult-rest#247 endpoint.
In the new pagination refactoring spec, the pagination property is set to be optional which should be mandatory I think
ATM is not trivial to check the status of a transaction by just looking at the payload. The client and SDKs need to assume the value by checking at the metadata to see if there is a height or not (for example) or by knowing if the transaction was loading using a rest endpoint or another (like group: partial)
I would like to add a status to the transaction, probably inside the meta payloads like:
meta: {status: partial | confirmed | unconfirmed | error?}
Unsure if it makes sense to add it to embedded transactions too. I guess it does if embedded transactions are loaded as top-level search results.
For an aggregate bonded transaction when it first gets submitted, it goes to the pt cache(partial transaction queue) and wait for cosigners to sign the tx. When the transaction is in this queue the state should be partial.e.g. Below is the status of a transaction from rest gateway when in that queue.
{"group":"partial","code":"Success","hash":"F7A99B130CFD5641B71CCABC538CE893164AF84229076541A9C8A47F1BF90677","deadline":"5520432181","height":"0"}
Originally posted by @Wayonb in https://github.com/nemtech/nem2-sdk-java/pull/195
Once we have a new version I can add that value to the java enum value.
WIP in #5
Initial endpoints proposal targeting accounts, should be duplicated per mosaic and namespaces.
GET /account/{accountId}/metadata/
Returns the complete accountId current state metadata. Ideally with pagination + order.
GET /account/{accountId}/metadata/{key}
Returns all the account current state metadata for that key. The response should be an array, as multiple signers can add metadata with the same key.
POST /account/{accountId}/metadata
Returns metadadata for an array of accountIds.
Let's use this issue to discuss changes in those endpoints and discuss if we need more of them.
Next release will come with two new transaction types. Additional info will be disclosed with the finalization design.
Catbuffer changes: https://github.com/nemtech/catbuffer/compare/783fdaf732db81d247fe862a8703e3b619aadf57...master
Hi @dgarcia360
Open API specifies that the valueSize should be present in Account/Mosaic/Namespace metadata transactions, for example:
https://github.com/nemtech/nem2-openapi/blob/master/spec/openapi3.yaml#L2649
It seems like Rest is not providing the valueSize anymore (@Vektrat ):
valueSize is not required by catbuffer but it used to be provided in the rest transaction payloads. Is this valueSize required? Do we need it to calculate the new delta when updating metadata or can we just remove it from the open API spec? @rg911?
still using senderPublicKey, should be senderAddress
Originally reported by @rg911
The rest sever only takes one public key or address after calling POST /account/. In our current DTO definition, we have both keys set as optional.
The problem comes after generating the typescript client with openapi-generator. Although we provide only one of the ids, the other key is still in the model showing as undefined which causes the error.
Let's use the issue to discuss possible solutions.
Hi guys, the nonce value in the MosaicDefinitinoTransaction is overflowing in Java and it will overflow in other languages
com.fasterxml.jackson.databind.JsonMappingException: Numeric value (3143697214) out of range of int (-2147483648 - 2147483647)
at [Source: (String)"{"deadline":"16039398229","divisibility":4,"duration":"100","entityBody_Reserved1":0,"flags":7,"id":"13C22C203106ED04","maxFee":"1000000","network":152,"nonce":3143697214,"signature":"ADFAABBEB2C29B0A6665CCE3BB1E575387F43A0D010372415360AAB29C25C91ADCFC93B3C5542BE55630941FDD0D540E5A4B1495F2AA8885A49A8C3C35D68D0B","signerPublicKey":"085ADC6A515307DA80727293C081550FD138B8B97D16CA338F43F2A821555E2A","type":16717,"verifiableEntityHeader_Reserved1":0,"version":1}"; line: 1, column: 161] (through reference chain: io.nem.symbol.sdk.openapi.vertx.model.MosaicDefinitionTransactionDTO["nonce"])
2 possible solutions
Reported by @fullcircle23
I would like to propose add new endpoint to get harvester infomation.
Reason
Route
/harvesters
/harvesters/{accountId}
Example HarvesterDTO
address : '9081FCCB41F8C8409A9B99E485E0E28D23BD6304EF7215E01A'
totalHarvestedBlocks : 100
totalHarvestedFees: 2300.000000
lastHarvestedBlock : '23410'
Remark
/harvesters queries may cost inefficient performance for rest endpoint, not sure using pagination will resolved the issue.feedback are welcome.
For account key link transaction, the remotePublicKey property need to get rename to linkedPublicKey. This is causing failures in the SDK.
{"meta":{"height":"333","hash":"86D317C374E4552A27850A3CC5776446903835CFCD75740FBBDBB483AA5EE05C","merkleComponentHash":"86D317C374E4552A27850A3CC5776446903835CFCD75740FBBDBB483AA5EE05C","index":0,"id":"5EC4505DB8551373BD6D227B"},"transaction":{"signature":"837A63D8869F7D3C28983B273A580BC46CD1B4A395954A9DC96FE2F99527CEF756DF463CF695D7B3C1426834F11C69FF8180D8FEF37211577EB8AC124A229004","signerPublicKey":"89589C81C500A65F4019DAD36198230373EBC2C646D3FDD0DDD3D966404559D4","version":1,"network":152,"type":16716,"maxFee":"16100","deadline":"16500718888","linkedPublicKey":"cbJOSD9mbSB8tSpqbYyAw/60wWIFVGji0vtY1LDuzWc=","linkAction":1}}
Caused by: java.lang.IllegalArgumentException: Public key is not valid
at io.nem.symbol.core.crypto.RawAddress.generateAddress(RawAddress.java:56) ~[symbol-sdk-core-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.model.account.Address.createFromPublicKey(Address.java:144) ~[symbol-sdk-core-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.model.account.PublicAccount.(PublicAccount.java:34) ~[symbol-sdk-core-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.model.account.PublicAccount.createFromPublicKey(PublicAccount.java:46) ~[symbol-sdk-core-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.mappers.AccountKeyLinkTransactionMapper.createFactory(AccountLinkTransactionMapper.java:43) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.mappers.AccountKeyLinkTransactionMapper.createFactory(AccountLinkTransactionMapper.java:32) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.mappers.AbstractTransactionMapper.createModel(AbstractTransactionMapper.java:75) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.mappers.AbstractTransactionMapper.map(AbstractTransactionMapper.java:67) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.mappers.GeneralTransactionMapper.map(GeneralTransactionMapper.java:89) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.nem.symbol.sdk.infrastructure.vertx.TransactionRepositoryVertxImpl.toTransaction(TransactionRepositoryVertxImpl.java:76) ~[symbol-sdk-vertx-client-0.17.2-20200516.002415-7.jar:?]
at io.reactivex.internal.operators.observable.ObservableMap$MapObserver.onNext(ObservableMap.java:59) ~[rxjava-2.1.7.jar:?]
at io.reactivex.internal.operators.observable.ObservableOnErrorNext$OnErrorNextObserver.onNext(ObservableOnErrorNext.java:68) ~[rxjava-2.1.7.jar:?]
at io.reactivex.internal.operators.single.SingleToObservable$SingleToObservableObserver.onSuccess(SingleToObservable.java:59) ~[rxjava-2.1.7.jar:?]
at io.vertx.reactivex.core.impl.AsyncResultSingle.lambda$subscribeActual$0(AsyncResultSingle.java:41) ~[vertx-rx-java2-3.5.0.jar:?]
at io.nem.symbol.sdk.openapi.vertx.invoker.ApiClient.lambda$buildResponseHandler$7(ApiClient.java:599) ~[symbol-openapi-vertx-client-0.8.10.jar:?]
at io.vertx.ext.web.client.impl.HttpContext.lambda$null$0(HttpContext.java:125) ~[vertx-web-client-3.5.0.jar:?]
Update the OpenAPI spec symbol/catapult-rest#248
Several DTO uses the anyOf keyword when they should be using the oneOf keyword. The reason behind this intentional change allows us to generate code that compiles. At the current moment, most openapi-generators do not support code generation with oneOf keyword.
Rules of usage, according to the docs:
If you want to contribute to this issue, you can coordinate with the openapi-generator community to apply the necessary changes for better support of the OAS3 specific keywords.
https://nemtech.github.io/symbol-openapi/#operation/getAccountOutgoingTransactions There are difference between the actual data and openapi sample.
Hi @dgarcia360
I've revisited one of the endpoints. I want to map the possible string values of http://localhost:3000/network to the NetworkType enums we use.
At the moment, open API doesn't specify those values, just the mijinTest example. Would it possible to add all the examples or even better change the name type to enum? It's hard to tell which are the expected values from other networks.
The workaround is using /node/info endpoint to know easily know the network type.
Hi @dgarcia360 ,
I'm doing some integration tests and I noticed that the HaskLockTranscation returned by rest doesn't have the format defined in the open API spec. The rest payload doesn't have the nested mosaic object, it just has the mosaicId and the amount. Is this an open API issue or a rest issue? @Vektrat?
I think at this stage is easier to fix the open API than rest and TS SDK (@rg911). Please notice that Java SDK uses the object generated from the open API spec. I would need to patch the open API spec in order to fix the Java SDK.
https://github.com/nemtech/nem2-openapi/blob/master/spec/openapi3.yaml#L2287
GenerationHash has been changed to GenerationHashSeed in NetworkProperties
One of the reasons for not having separated metadata was due to previous account restrictions endpoint structure.
Taking into consideration similar features that depend on others (restrictions, multisig), we are creating endpoints under each main independent concept (e.g. /account/<:accountId>/restrictons).
#28 changes the /restrictions endpoints and opens the door to reorganize metadata endpoints.
The does not change the number of endpoints or responses, but how they are called. Repeat changing /account/{accountId} for mosaic and namespaces endpoints.
| Previous Endpoint | New endpoint |
|---|---|
| /account/{accountId}/metadata/ | /metadata/account/{accountId} |
| /account/{accountId}/metadata/{key} | /metadata/account/{accountId}/key/{key} |
| /account/{accountId}/metadata/{key}/sender/{publicKey} | /metadata/account/{accountId}/key/{key}/sender/{publicKey} |
@Vektrat @rg911 @fboucquez Let me know if do you have any objection/improvements.
namespaceId should be changed to id
BlockInfo.id should NOT nullable
OpenAPI Generator for Python auto-generates fully formed test cases in Travis-CI. These tests revealed possible issues and/or room for improvements in the OpenAPI spec.
The first type of issue that broke several tests with invalid syntax error are the single quotes in example values. Screenshot of the errors (sample) in travis job log below or view the raw log.
Examples of the OpenAPI spec that caused the error:
Example 1:
maxTransactionsPerAggregate:
type: string
description: Maximum number of transactions per aggregate.
example: 1'000
Example 2:
currencyMosaicId:
type: string
description: Mosaic id used as primary chain currency.
example: 0x621E'C5B4'0385'6FC2
The fix is to remove the single quotes in the example values.
1.) 1'000 is replaced with 1000
2.) 0x621E'C5B4'0385'6FC2 is replaced with 0x621EC5B403856FC2
Altogether, the invalid syntax errors were found in 12 test cases and the corresponding values (with some repeats) are as follows:
As a workaround, I've added a script in existing download-and-patch.sh to fix the above values. I've also attached the openapi yml with and without the single quote fix patch for comparison:
openapi3-any-of-patch.yml.txt
openapi3-any-of-patch-single-quote-patch.yml.txt
@dgarcia360 I can also fix the above values in the spec files in this repo and remove the workaround patch. Please let me know.
I'm also looking into the other failed test cases.
Depending on the location of the transaction returned by rest, the database id can be at top level or inside the meta object. I would like to improve this by making all the objects (top-level or embedded) to have the id in the same place, ideally at top level (outside meta) like other similar stored entities.
This change will simplify the open api specification and the mappers in the clients/SDKs
Search page has ids at top level,
By id/s has ids at meta-level:
@Vektrat, is it possible to implement the improvement in rest?
Transaction endpoints may return single, list or pages of embedded transactions but the spec only states top-level transactions
For example:
Something similar to pages of transactions when embedded=true
It is rather aggregateHash instead of just hash
When generating the objects, aggregateHash and aggregateId are ignored from top level transactions and clients cannot create the standalone embedded transactions
Due to mongoDB schema changes: https://github.com/nemtech/catapult-server/blob/master/src/catapult/state/AccountKeys.h#L34
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.