restub 0.18.9
dotnet add package restub --version 0.18.9
NuGet\Install-Package restub -Version 0.18.9
<PackageReference Include="restub" Version="0.18.9" />
paket add restub --version 0.18.9
#r "nuget: restub, 0.18.9"
// 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
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
- Make sure that
nbgv
dotnet CLI tool is installed and is up to date - Run
nbgv prepare-release
to create a stable branch for the upcoming release, i.e. release/v1.0 - Switch to the release branch:
git checkout release/v1.0
- Execute unit tests, update the README, release notes in csproj file, etc. Commit and push your changes.
- Run
dotnet pack -c Release
and check that it builds Nuget packages with the right version number. - 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. - Push tags as suggested by nbgv tool:
git push origin v1.0.7
- Go to github project page and create a release out of the last tag v1.0.7.
- Verify that github workflow for publishing the nuget package has completed.
- Switch back to master and merge the release branch.
Product | Versions 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. |
-
.NETFramework 4.6.2
- Newtonsoft.Json (>= 13.0.2)
- RestSharp (>= 106.15.0)
-
net6.0
- Newtonsoft.Json (>= 13.0.2)
- RestSharp (>= 106.15.0)
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.