restub 0.18.9

dotnet add package restub --version 0.18.9                
NuGet\Install-Package restub -Version 0.18.9                
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="restub" Version="0.18.9" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add restub --version 0.18.9                
#r "nuget: restub, 0.18.9"                
#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 restub as a Cake Addin
#addin nuget:?package=restub&version=0.18.9

// Install restub as a Cake Tool
#tool nuget:?package=restub&version=0.18.9                

restub

.NET CodeFactor .NET Framework 4.62 .NET 6.0 NuGet

Build your traceable REST API client with a few lines of code.

Welcome

restub is a stub framework for implementing REST API clients with built-in tracing.
Trace log contains all requests, responses, headers, parameters, error codes and timings.
Uses RestSharp library and Newtonsoft.Json serializer behind the scenes.

Getting started

  • Add the Nuget package: https://www.nuget.org/packages/restub
  • Subclass RestubClient, add REST API methods
  • Implement request and response classes used by your REST API service
  • Add authentication support by subclassing Authenticator, if needed

Sample REST client

public class GithubClient : RestubClient
{
  public GithubClient() : base("https://api.github.com/")
  { 
  }

  public GithubUser GetUser(string name) =>
    Get<GithubUser>($"users/{name}");
}

Sample DTO class

public class GithubUser
{
  public int ID { get; set; }
  public string Url { get; set; }
  public string Login { get; set; }
  public string Name { get; set; }
}

Sample REST client usage

// connect to Github API
var client = new GithubClient();

// trace all API calls to the console
client.Tracer = Console.WriteLine;

// get user by name
var orgs = client.GetUser("yallie");

Advantages

  • Get a full-featured REST API client with just a few lines of code
  • Execute HTTP GET, POST, HEAD, PUT, PATCH, OPTIONS or DELETE requests
  • Enable built-in tracing with a single line of code
  • Explore API calls logs within your IDE while running the unit tests
  • Use unannotated POCO classes for requests and responses
  • Enums serialized as numbers and/or strings can be mixed within the same API
  • Optionally add standard DataMember/EnumMember attributes for more control
  • Implement Authenticator if your API requires authentication
  • Supports synchronous and asynchronous request execution
  • Targets .NET 4.6.2 and .NET 6.0 frameworks

Disadvantages

  • No support for XML serialization
  • Depends on RestSharp and Newtonsoft.Json libraries.

Trace log

A typical trace log looks like this:

// GetAuthToken
-> POST https://api.edu.cdek.ru/v2/oauth/token?parameters
headers: {
  X-ApiClientName = restub v0.1.6.37278
  X-ApiMethodName = GetAuthToken
  Accept = application/json, text/json, text/x-json, text/javascript, application/xml, text/xml
  Content-type = application/json
}
body: null

<- OK 200 (OK) https://api.edu.cdek.ru/v2/oauth/token?parameters
timings: {
  started: 2022-09-23 19:51:16
  elapsed: 0:00:00.719
}
headers: {
  Transfer-Encoding = chunked
  Connection = keep-alive
  Keep-Alive = timeout=15
  Vary = Accept-Encoding
  Pragma = no-cache
  X-Content-Type-Options = nosniff
  X-XSS-Protection = 1; mode=block
  X-Frame-Options = DENY
  Content-Encoding = 
  Cache-Control = no-store
  Content-Type = application/json;charset=utf-8
  Date = Fri, 23 Sep 2022 16:51:18 GMT
  Server = QRATOR
}
body: {
  "access_token": "eyJhbGciOiJSUzI1Ni....eq62ZCji34UPjozvWCUXv16ZvTA",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "order:all payment:all",
  "jti": "be19866f-0d95-4287-b1ff-cad84e113c3c"
}

// GetRegions
-> GET https://api.edu.cdek.ru/v2/location/regions?size=3&page=2
headers: {
  X-ApiClientName = restub v0.1.6.37278
  X-ApiMethodName = GetRegions
  Authorization = Bearer eyJhbGciOiJSUzI1Ni....eq62ZCji34UPjozvWCUXv16ZvTA
  Accept = application/json, text/json, text/x-json, text/javascript, application/xml, text/xml
}

<- OK 200 (OK) https://api.edu.cdek.ru/v2/location/regions?size=2&page=3
timings: {
  started: 2022-09-23 19:55:56
  elapsed: 0:00:00.859
}
headers: {
  Transfer-Encoding = chunked
  Connection = keep-alive
  Keep-Alive = timeout=15
  Vary = Accept-Encoding
  X-Content-Type-Options = nosniff
  X-XSS-Protection = 1; mode=block
  Pragma = no-cache
  X-Frame-Options = DENY
  Content-Encoding = 
  Cache-Control = no-cache, no-store, max-age=0, must-revalidate
  Content-Type = application/json
  Date = Fri, 23 Sep 2022 16:55:58 GMT
  Expires = 0
  Server = QRATOR
}
body: [
  {
    "country_code": "FR",
    "country": "Франция",
    "region": "Марна",
    "region_code": 590
  },
  {
    "country_code": "FR",
    "country": "Франция",
    "region": "Ло и Гаронна",
    "region_code": 560
  }
]

restub versioning

The project uses Nerdbank.GitVersioning tool to manage versions.
Each library build can be traced back to the original git commit.

Preparing and publishing a new release

  1. Make sure that nbgv dotnet CLI tool is installed and is up to date
  2. Run nbgv prepare-release to create a stable branch for the upcoming release, i.e. release/v1.0
  3. Switch to the release branch: git checkout release/v1.0
  4. Execute unit tests, update the README, release notes in csproj file, etc. Commit and push your changes.
  5. Run dotnet pack -c Release and check that it builds Nuget packages with the right version number.
  6. Run nbgv tag release/v1.0 to tag the last commit on the release branch with your current version number, i.e. v1.0.7.
  7. Push tags as suggested by nbgv tool: git push origin v1.0.7
  8. Go to github project page and create a release out of the last tag v1.0.7.
  9. Verify that github workflow for publishing the nuget package has completed.
  10. Switch back to master and merge the release branch.
Product Compatible and additional computed target framework versions.
.NET 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 was computed.  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 was computed.  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 Framework net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on restub:

Package Downloads
PochtaSdk

Pochta.ru REST API client with tracing support.

CdekSdk

CDEK delivery company REST API client with tracing support.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.18.9 710 2/16/2023
0.17.5 684 11/25/2022
0.16.5 647 11/11/2022
0.15.5 658 10/31/2022
0.14.7 526 10/28/2022
0.13.6 643 10/26/2022
0.12.8 546 10/24/2022
0.11.8 590 10/19/2022
0.10.8 578 10/14/2022
0.9.8 443 10/14/2022
0.8.8 459 10/13/2022
0.7.6 459 10/8/2022
0.6.6 1,165 9/29/2022
0.5.6 463 9/28/2022
0.4.7 504 9/27/2022
0.3.6 756 9/25/2022
0.2.11 483 9/24/2022
0.1.7 497 9/23/2022

Beta release. What's new:

   v0.18
   — #31 Added BeforeExecute and AfterExecute virtual methods
   — #30 Updated Newtonsoft.Json to version 13.0.2
   — #29 Implemented automatic cookie management

   v0.17
   — #27 Fixed missing Content-type header when request body is not supplied

   v0.16
   — #26 Fixed a tracing issue with REST API methods returning PDF files

   v0.15
   — #25 Added BoolIntConverter

   v0.14
   — #23 JsonFormatter helper class is now public
   — #24 Added RestubException.ErrorResponseText property

   v0.13
   — #22 Added support for byte[] return type for downloading small files

   v0.12
   — #21 Added DisplayAttribute support for supplying names for enum values

   v0.11
   — #18 Added DefaultEnumMemberAttribute to handle missing enum values
   — #19 Added extension methods and unit tests from PochtaSdk library

   v0.10
   — #15 SourceLink: embed the untracked sources
   — #16 Allow returning the rest client as IAuthenticator
   — #17 Renamed CreateEncoding to GetEncoding, CreateAuthenticator to GetAuthenticator

   v0.9
   — #13 Added SourceLink, enabled deterministic release builds
   — #14 Added AuthHeaders to the base Authenticator class

   v0.8
   — #11 ErrorResponse deserialization extension point
   — #12 Base Authenticator class now has 2 generic arguments instead of 3

   v0.7
   — #10 RestubException inner exception argument is now optional
   — #9 Added virtual method CreateException for replaceable exception classes
   — #8 CreateAuthenticator now returns IAuthenticator for more flexibility

   v0.6
   — #7 Added IRestubSerializer interface for easier unit testing.

   v0.5
   — #6 Encoding is now customizable.
   — #5 Fixed enum array parameters serialization in query strings.

   v0.4
   — #4 AddParameters now ignores members marked with IgnoreDataMemberAttribute.

   v0.3
   — #3 Better support for enum serialization.

   v0.2
   — #2 Added support for asynchronous method execution.
   — #1 Added support for HTTP PUT, PATCH, HEAD, OPTIONS, DELETE verbs.

   v0.1
   — Initial beta release.