Open API Critique
Open API Critique
08 Jan 2021, 11:09
After spending two days deciphering the .NET version of Open APIs, here is my critique.
Misleading Name
The term open apis is conflicting with the Open API and Swagger which is about RESTful APIs. What Spotware really meant by the term open is not their B2B APIs but the APIs open for the public! In brief, the name should be meaningful to the developers or traders and not necessarily meaningful to Spotware, Open implies REST and Swagger.
Naming Conventions
The sample SDK for .NET violates plenty of .NET conventions, let's start:
- "Open API Library" has spaces, usually a project name is the same as the namespace. This practice is also using a non .NET style namespace, of Open_API_Library
- _msg for a local variable name is not a .NET convention (not Java, not Python, not JavaScript, not TypeScript, not VB, not VBA).
- Another example is: app_auth_req which is not .NET but Python convention. Why having two alien conventions for a local variable? Only Spotware knows...
Bug
I discovered a bug while reading the source code:
"PotoOATraderReq" it should be "ProtoOATraderReq"
The Winforms Sample
You would expect in any SDK to have the following format:
Create a context which you pass to some parameters like the host, port, maybe some credentials.
CTraderAPIContext ctx = new CTraderAPIContext(...)
ctx.AuthenticateApp(...)
ctx.AnotherService(...)
ctx.Dispose()
But what I found is a mix of protocols that forces the developer to understand, by reverse engineering the code. As a developer, what I am more concerned about is calling the right method in the right order and not about knowing the plumbing of what is happening on the wire (I would trust that Spotware had taken care of that).
What I found instead is a mix of protocols, and calling different methods like Transmit to push the content on the wire.
In brief, Spotware did not do a good job abstracting the protocols and leave a clean interface for the developer.
Documentation
The documentation doesn't tell you what needs to happen to send a call to the server. What I am expecting:
- We are using TcpIP over SSL, so you will have to do the following...
- Every message that we get should be on the form of ProtoMessage serialized as ByteString (or something like that) (unless if the SDK has absorbed this implementation and the developer doesn't have to write it, you do not have to document it, but it is the developer responsibility and it is not documented).
They tried to document it by example, but the example is not well-written in the first place.
A message to Spotware: You have built beautiful APIs for the cAutomate and set the bar high, however, the architecture of the Open APIs are not up to the scratch.
Replies
ctid402288
31 Jul 2022, 20:43
( Updated at: 31 Jul 2022, 20:53 )
I have to agree with JeanPaul on this topic. JeanPaul has not listed a comprehensive list of all the issues with the openapi. A sample should compile and reflect the actual working of the API. More importantly, the documentation should reflect the functions [or methods] used in the sample. All aspect of the sample should be transferable to other SDKs in the CTrader OpenAPI suite.
Take this line of code for example : -[WPF Sample] Pips = Symbol.Data.GetPipsFromPrice(Symbol.Bid - Price); This refers to the following "public ProtoOASymbol Data { get; init; }" in the SymbolModel class. The documentation for ProtoOASymbol does not show any functions associated with it. One can therefore assume that all classes in the documentation have some undocumented methods inherently in them. Admittedly, l am writing in Python and the OpenAPIPy documentation do not have the aforementioned information. As using this OpenAPI involves risking money, it is problematic for one to be losing money due to poor understanding of the OpenAPI. You should make an effort to improve the documentation and samples to better support developers and prevent unnecessary loss of money that may result from the documentation as it stands at the moment.
@ctid402288
giuseppesciacovelli9
21 Aug 2022, 14:23
Dynamic co-management window.
Good morning, since the problems are many proporei to outline the flow from the URL and subsequent acknowledgments including Demo and LIve. ... and I don't go into the problems that Windows creates as an Operating System, perhaps Linux would be better. After that I would divide the data, as type, and I would send them with messages in parallel or in batch so we can put more because it only has to identify the packet and we will go faster. Joseph
@giuseppesciacovelli9
PanagiotisCharalampous
08 Jan 2021, 11:51 ( Updated at: 08 Jan 2021, 12:01 )
Hi JeanPaul,
We appreciate your constructive criticism and we are seriously taking them into consideration
Misleading Name
It used to be a REST based API which we converted to a Protocol Buffers API. We kept the name though. Some comments below
Naming Conventions
You are right about this. The current sample is a community project and an amalgamation of previous community based samples which did not go through a proper software lifecycle process, neither do they adhere to serious coding standards.
Bug
Thanks for spotting, we will fix it
The Winforms Sample
Same as above. This is not an SDK or something we propose users to use to build production code on top. The sole purpose of this sample is to give people not familiar with Protocol Buffers an idea how to send and receive messages. That's all. Up to now it serves it's purpose well. We plan to build a comprehensive SDK using proper coding and quality standards in the future.
Documentation
Your suggestions are noted and we will try to improve the documentation.
Best Regards,
Panagiotis
Join us on Telegram
@PanagiotisCharalampous