JadeX.AllegroAPI 1.0.0-alpha.2

.NET 6.0 .NET Standard 2.0
This is a prerelease version of JadeX.AllegroAPI. 
dotnet add package JadeX.AllegroAPI --version 1.0.0-alpha.2
NuGet\Install-Package JadeX.AllegroAPI -Version 1.0.0-alpha.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="JadeX.AllegroAPI" Version="1.0.0-alpha.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add JadeX.AllegroAPI --version 1.0.0-alpha.2
#r "nuget: JadeX.AllegroAPI, 1.0.0-alpha.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install JadeX.AllegroAPI as a Cake Addin
#addin nuget:?package=JadeX.AllegroAPI&version=1.0.0-alpha.2&prerelease

// Install JadeX.AllegroAPI as a Cake Tool
#tool nuget:?package=JadeX.AllegroAPI&version=1.0.0-alpha.2&prerelease

Allegro.pl REST API

License NuGet Downloads NuGet .NET Standard .NET 6-8 build

Unofficial implementation of Allegro.pl commerce platform REST API for .NET as documented on https://developer.allegro.pl

ko-fi

[!WARNING]

Current state: ALPHA

All endpoints are code-generated providing entirety of the API for consumption. Please be advised IAllegroApi.generated.cs may change dramatically between regenerations requiring substantial code changes for calling API endpoints. Needs better deterministic name generation handling.

Highlights

Function Description
Strongly-typed API communication With Refit REST library, communication with Allegro API is conducted in a type-safe manner, no magic strings or studying documentation necessary, everything is in the IntelliSense.
Code generated OpenAPI endpoints All endpoints are code generated from most current OpenAPI specification published by Allegro.pl using Refitter, therefore is always up-to-date, error-prone and includes full IntelliSense.
Authentication API When instance is provided with valid credentials & refresh token, library will ensure all requests have valid authentication headers. Tokens are validated and automatically refreshed only as needed. <br> Only device flow is currently supported.

Install with NuGet

dotnet add package JadeX.AllegroAPI --prerelease

Basic Usage (Console)

[!IMPORTANT] Make sure you have registered your application with Allegro API Apps (Sandbox) or Allegro API Apps (Production), for this you need active account on respective environment. Take note of CLIENT ID and CLIENT SECRET.

using JadeX.AllegroAPI;

var allegroRestClient = new AllegroRestClient(x =>
{
    x.Environment = AllegroEnvironment.Sandbox;
    x.Authentication.Flow = AuthenticationFlow.Device;
    x.Authentication.ClientId = "{YOUR CLIENT ID}";
    x.Authentication.ClientSecret = "{YOUR CLIENT SECRET}";
});

var deviceCodeResponse = await allegroRestClient.AuthenticationService.GetDeviceCode().ConfigureAwait(false); // Don't call this very often
Console.WriteLine($"Open {deviceCodeResponse.VerificationUrlComplete} in browser and follow instructions there ... Once finished, press enter to obtain access token and call some API endpoint.");
Console.ReadLine();
await allegroRestClient.AuthenticationService.GetAccessTokens().ConfigureAwait(false); // Valid for 12 hours, need to call RefreshTokens() afterwards

// Now it's possible to call API enpoints

var offers = await allegroRestClient.API.SearchOffersUsingGET(limit: 1).ConfigureAwait(false);
Console.Write($"You have total of {offers.TotalCount} offers.");
if (offers.TotalCount > 0)
{
    Console.WriteLine($" First one is called '{offers.Offers?.First().Name}'.");
}

var orderEvents = await allegroRestClient.API.GetOrderEventsUsingGET().ConfigureAwait(false);
Console.WriteLine($"There is total of {orderEvents.Events.Count} order events:");
Console.WriteLine("Types are: " + string.Join(", ", orderEvents.Events.Select(x => x.Type.ToString())));
Console.ReadLine();

[!CAUTION] You can't get access tokens with GetAccessTokens() until device code is validated with browser under desired user account (link in VerificationUrlComplete)!

Advanced Authentication

Clearly previous example is handling authentication very poorly, calling GetDeviceCode() every time instance is created is not just incredibly cumbersome, but deemed unwated by the API and will very soon hit rate limiter like requiring solving CAPTCHA. To solve this AccessToken and RefreshToken need to be reused.

[!TIP] AllegroRestClient remembers most recent device code and access/refresh tokens internally, you should deal with them only during initialization.

using JadeX.AllegroAPI;

var AllegroRestClient = new AllegroRestClient(x =>
{
    x.Environment = AllegroEnvironment.Sandbox;
    x.Authentication.Flow = AuthenticationFlow.Device;
    x.Authentication.ClientId = "{YOUR CLIENT ID}";
    x.Authentication.ClientSecret = "{YOUR CLIENT SECRET}";

    x.Authentication.RefreshToken = "{retrieve your RefreshToken from secure persistent storage}";
    // While not absolutely necessary you can also store/retrieve AccessToken, prevents unnecessary token refresh (especially useful in testing).
    x.Authentication.AccessToken = "{retrieve your AccessToken from secure persistent storage}";

    x.Authentication.OnAccessTokenChanged += OnAccessTokenChanged;
    x.Authentication.OnRefreshTokenChanged += OnRefreshTokenChanged;
});

static void OnAccessTokenChanged(object? sender, string? accessToken)
{
    // Store new accessToken in secure persistent storage like database or user-secrets file
}

static void OnRefreshTokenChanged(object? sender, string? refreshToken)
{
    // Store new refreshToken in secure persistent storage like database or user-secrets file
}

Versioning Scheme

This library is using SemVer 2.0.0 as it's versioning scheme.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-alpha.2 66 3/3/2024
1.0.0-alpha.1 48 2/29/2024

See https://github.com/JadeX/AllegroAPI/releases/tag/1.0.0-alpha.2