From b65669659d189066d0ef6e19ff9c02fb27cd18f1 Mon Sep 17 00:00:00 2001 From: Jkorf Date: Mon, 17 Jan 2022 13:44:45 +0100 Subject: [PATCH] docs --- docs/Clients.md | 53 ++++++++++++++++++++++------------------- docs/FAQ.md | 17 ++++++++----- docs/Glossary.md | 5 ++++ docs/Interfaces.md | 5 ++++ docs/Logging.md | 5 ++++ docs/Migration Guide.md | 5 ++++ docs/Options.md | 5 ++++ docs/Orderbooks.md | 5 ++++ docs/index.md | 21 +++++++++------- 9 files changed, 83 insertions(+), 38 deletions(-) diff --git a/docs/Clients.md b/docs/Clients.md index 4852847..04803fe 100644 --- a/docs/Clients.md +++ b/docs/Clients.md @@ -1,3 +1,8 @@ +--- +title: General usage +nav_order: 2 +--- + Each implementation generally provides two different clients, which will be the access point for the API's. First of the rest client, which is typically available via [ExchangeName]Client, and a socket client, which is generally named [ExchangeName]SocketClient. For example `BinanceClient` and `BinanceSocketClient`. ## Rest client @@ -15,10 +20,10 @@ The rest client gives access to the Rest endpoint of the API. Rest endpoints are This rest client has 2 different API clients, the `SpotApi` and the `FuturesApi`, each offering their own set of endpoints. *Requesting ticker info on the spot API* -````C# +```csharp var client = new KucoinClient(); var tickersResult = kucoinClient.SpotApi.ExchangeData.GetTickersAsync(); -```` +``` Structuring the client like this should make it easier to find endpoints and allows for separate options and functionality for different API clients. For example, some API's have totally separate API's for futures, with different base addresses and different API credentials, while other API's have implemented this in the same API. Either way, this structure can facilitate a similar interface. @@ -46,7 +51,7 @@ Each request will return a WebCallResult with the following properties: When processing the result of a call it should always be checked for success. Not doing so will result in `NullReference` exceptions. *Check call result* -````C# +```csharp var callResult = await kucoinClient.SpotApi.ExchangeData.GetTickersAsync(); if(!callResult.Success) { @@ -55,43 +60,43 @@ if(!callResult.Success) } Console.WriteLine("Result: " + callResult.Data); -```` +``` ## Socket client The socket client gives access to the websocket API of an exchange. Websocket API's offer streams to which updates are pushed to which a client can listen. Some exchanges also offer some degree of functionality by allowing clients to give commands via the websocket, but most exchanges only allow this via the Rest API. Just like the Rest client is divided in Rest Api clients, the Socket client is divided into Socket Api clients, each with their own range of API functionality. Socket Api clients are generally not divided into topics since the number of methods isn't as big as with the Rest client. To use the Kucoin client as example again, it looks like this: -````C# +```csharp - KucoinSocketClient - SpotStreams - FuturesStreams -```` +``` *Subscribing to updates for all tickers on the Spot Api* -````C# +```csharp var subscribeResult = kucoinSocketClient.SpotStreams.SubscribeToAllTickerUpdatesAsync(DataHandler); -```` +``` Subscribe methods require a data handler parameter, which is the method which will be called when an update is received from the server. This can be the name of a method or a lambda expression. *Method reference* -````C# +```csharp await kucoinSocketClient.SpotStreams.SubscribeToAllTickerUpdatesAsync(DataHandler); private static void DataHandler(DataEvent updateData) { // Process updateData } -```` +``` *Lambda* -````C# +```csharp await kucoinSocketClient.SpotStreams.SubscribeToAllTickerUpdatesAsync(updateData => { // Process updateData }); -```` +``` All updates are wrapped in a `DataEvent<>` object, which contain a `Timestamp`, `OriginalData`, `Topic`, and a `Data` property. The `Timestamp` is the timestamp when the data was received (not send!). `OriginalData` will contain the originally received data if this has been enabled in the client options. `Topic` will contain the topic of the update, which is typically the symbol or asset the update is for. The `Data` property contains the received update data. @@ -99,7 +104,7 @@ All updates are wrapped in a `DataEvent<>` object, which contain a `Timestamp`, ### Processing subscribe responses Subscribing to a stream will return a `CallResult` object. This should be checked for success the same was as the [rest client](#processing-request-responses). The `UpdateSubscription` object can be used to listen for connection events of the socket connection. -````C# +```csharp var subscriptionResult = await kucoinSocketClient.SpotStreams.SubscribeToAllTickerUpdatesAsync(DataHandler); if(!subscriptionResult.Success) @@ -116,44 +121,44 @@ subscriptionResult.Data.ConnectionRestored += (time) => Console.WriteLine("Connection restored"); }; -```` +``` ### Unsubscribing When no longer interested in specific updates there are a few ways to unsubscribe. **Close subscription** Subscribing to an update stream will respond with an `UpdateSubscription` object. You can call the `CloseAsync()` method on this to no longer receive updates from that subscription: -````C# +```csharp var subscriptionResult = await kucoinSocketClient.SpotStreams.SubscribeToAllTickerUpdatesAsync(DataHandler); await subscriptionResult.Data.CloseAsync(); -```` +``` **Cancellation token** Passing in a `CancellationToken` as parameter in the subscribe method will allow you to cancel subscriptions by canceling the token. This can be useful when you need to cancel some streams but not others. In this example, both `BTC-USDT` and `ETH-USDT` streams get canceled, while the `KCS-USDT` stream remains active. -````C# +```csharp var cts = new CancellationTokenSource(); var subscriptionResult1 = await kucoinSocketClient.SpotStreams.SubscribeToTickerUpdatesAsync("BTC-USDT", DataHandler, cts.Token); var subscriptionResult2 = await kucoinSocketClient.SpotStreams.SubscribeToTickerUpdatesAsync("ETH-USDT", DataHandler, cts.Token); var subscriptionResult3 = await kucoinSocketClient.SpotStreams.SubscribeToTickerUpdatesAsync("KCS-USDT", DataHandler); Console.ReadLine(); cts.Cancel(); -```` +``` **Client unsubscribe** Subscriptions can also be closed by calling the `UnsubscribeAsync` method on the client, while providing either the `UpdateSubscription` object or the subscription id: -````C# +```csharp var subscriptionResult = await kucoinSocketClient.SpotStreams.SubscribeToTickerUpdatesAsync("BTC-USDT", DataHandler); await kucoinSocketClient.UnsubscribeAsync(subscriptionResult.Data); // OR await kucoinSocketClient.UnsubscribeAsync(subscriptionResult.Data.Id); -```` +``` When you need to unsubscribe all current subscriptions on a client you can call `UnsubscribeAllAsync` on the client to unsubscribe all streams and close all connections. ## Dependency injection Each library offers a `Add[Library]` extension method for `IServiceCollection`, which allows you to add the clients to the service collection. It also provides a callback for setting the client options. See this example for adding the `BinanceClient`: -````C# +```csharp public void ConfigureServices(IServiceCollection services) { services.AddBinance((restClientOptions, socketClientOptions) => { @@ -163,11 +168,11 @@ public void ConfigureServices(IServiceCollection services) socketClientOptions.ApiCredentials = new ApiCredentials("KEY", "SECRET"); }); } -```` +``` Doing client registration this way will add the `IBinanceClient` as a transient service, and the `IBinanceSocketClient` as a scoped service. Alternatively, the clients can be registered manually: -````C# +```csharp BinanceClient.SetDefaultOptions(new BinanceClientOptions { ApiCredentials = new ApiCredentials("KEY", "SECRET"), @@ -181,4 +186,4 @@ BinanceSocketClient.SetDefaultOptions(new BinanceSocketClientOptions services.AddTransient(); services.AddScoped(); -```` +``` diff --git a/docs/FAQ.md b/docs/FAQ.md index f3b99da..f993c63 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,6 +1,11 @@ +--- +title: FAQ +nav_order: 9 +--- + ### I occasionally get a NullReferenceException, what's wrong? You probably don't check the result status of a call and just assume the data is always there. `NullReferenceExecption`s will happen when you have code like this `var symbol = client.GetTickersAync().Result.Data.Symbol` because the `Data` property is null when the call fails. Instead check if the call is successful like this: -````C# +```csharp var tickerResult = await client.GetTickersAync(); if(!tickerResult.Success) { @@ -11,12 +16,12 @@ else // Handle result, it is now safe to access the Data property var symbol = tickerResult.Data.Symbol; } -```` +``` ### The socket client stops sending updates after a little while You probably didn't keep a reference to the socket client and it got disposed. Instead of subscribing like this: -````C# +```csharp private void SomeMethod() { var socketClient = new BinanceSocketClient(); @@ -24,9 +29,9 @@ private void SomeMethod() // Handle data }); } -```` +``` Subscribe like this: -````C# +```csharp private BinanceSocketClient _socketClient = new BinanceSocketClient(); // .. rest of the class @@ -38,4 +43,4 @@ private void SomeMethod() }); } -```` \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/Glossary.md b/docs/Glossary.md index 11646e0..ea3e4b2 100644 --- a/docs/Glossary.md +++ b/docs/Glossary.md @@ -1,3 +1,8 @@ +--- +title: Glossary +nav_order: 8 +--- + |Definition|Synonyms|Meaning| |----------|--------|-------| |Symbol|Market|An asset pair, for example `BTC-ETH`| diff --git a/docs/Interfaces.md b/docs/Interfaces.md index 9f326ac..c60d17c 100644 --- a/docs/Interfaces.md +++ b/docs/Interfaces.md @@ -1,3 +1,8 @@ +--- +title: Common interfaces +nav_order: 5 +--- + ## ISpotClient TODO diff --git a/docs/Logging.md b/docs/Logging.md index bfa200d..4970455 100644 --- a/docs/Logging.md +++ b/docs/Logging.md @@ -1,3 +1,8 @@ +--- +title: Log config +nav_order: 4 +--- + The library offers extensive logging, for which you can supply your own logging implementation. The logging can be configured via the client options (see [Client options](https://github.com/JKorf/CryptoExchange.Net/wiki/Options)). The examples here are using the `BinanceClient` but they should be the same for each implementation. Logging is based on the `Microsoft.Extensions.Logging.ILogger` interface. This should provide ease of use when connecting the library logging to your existing logging implementation. diff --git a/docs/Migration Guide.md b/docs/Migration Guide.md index 3c5a445..849e782 100644 --- a/docs/Migration Guide.md +++ b/docs/Migration Guide.md @@ -1,3 +1,8 @@ +--- +title: Migrate v4 to v5 +nav_order: 7 +--- + Changes from 4.x to 5.x: ## Client structure diff --git a/docs/Options.md b/docs/Options.md index 8c2f3d5..b9c8a5e 100644 --- a/docs/Options.md +++ b/docs/Options.md @@ -1,3 +1,8 @@ +--- +title: Client options +nav_order: 3 +--- + ## Setting options Each implementation can be configured using client options. There are 2 ways to provide these, either via `[client].SetDefaultOptions([options]);`, or in the constructor of the client. The examples here use the `BinanceClient`, but usage is the same for each client. diff --git a/docs/Orderbooks.md b/docs/Orderbooks.md index 83d6274..dbee800 100644 --- a/docs/Orderbooks.md +++ b/docs/Orderbooks.md @@ -1,3 +1,8 @@ +--- +title: Order books +nav_order: 6 +--- + Each implementation provides an order book implementation. These implementations will provide a client side order book and will take care of synchronization with the server, and will handle reconnecting and resynchronizing in case of a dropped connection. Order book implementations are named as `[ExchangeName][Type]SymbolOrderBook`, for example `BinanceSpotSymbolOrderBook`. diff --git a/docs/index.md b/docs/index.md index 9554f7d..6617b33 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,22 @@ +--- +title: Home +nav_order: 1 +--- + The CryptoExchange.Net library is a base package for exchange API implementations. -[Client usage](https://github.com/JKorf/CryptoExchange.Net/wiki/Clients) +[Client usage](Clients.html) -[Client options](https://github.com/JKorf/CryptoExchange.Net/wiki/Options) +[Client options](Options.html) -[Configure logging](https://github.com/JKorf/CryptoExchange.Net/wiki/Logging) +[Configure logging](Logging.html) -[Order book implementations](https://github.com/JKorf/CryptoExchange.Net/wiki/Orderbooks) +[Order book implementations](Orderbooks.html) -[Common interfaces](https://github.com/JKorf/CryptoExchange.Net/wiki/Interfaces) +[Common interfaces](Interfaces.html) -[Implementing a new exchange](https://github.com/JKorf/CryptoExchange.Net/wiki/Implementations) +[Implementing a new exchange](Implementations.html) -[Glossary](https://github.com/JKorf/CryptoExchange.Net/wiki/Glossary) +[Glossary](Glossary.html) -[FAQ](https://github.com/JKorf/CryptoExchange.Net/wiki/FAQ) +[FAQ](FAQ.html)