Skip to content

Latest commit

 

History

History
98 lines (65 loc) · 5.79 KB

README.md

File metadata and controls

98 lines (65 loc) · 5.79 KB
Raw

PortableRest 4.0

PortableRest is a Portable Class Library for implementing REST API clients in other Portable Class Libraries. It leverages JSON.NET for rapid, customizable serialization, as well as the Microsoft.Bcl.Async library for awaitable execution on any platform. It is designed to be largely drop-in compatible with RestSharp, though you will need to make some changes and recompile if you are upgrading from that solution.

Works on all .NET Standard 2.0 platforms.

Design Goals

  • Be able to write one REST client wrapper that can be used on all current-generation Microsoft platforms (without the techniques we have to use for XamlEssentials).
  • Have more control over serialization of property names (so you're not limited to the "remove all dashes" convention of RestSharp).
  • Be able to have objects be easily serializable to local storage using standard techniques, without jumping through a lot of hoops.

What's New?

Version 3.0

  • Added constructor overload that accepts a custom HttpMessageHandler for all requests the HttpClient makes.
  • Added support for using the AsyncOAuth NuGet package for leveraging OAuth in your requests.
  • Added support for specifying the JsonSerializerSettings on a client-wide or per-request basis, with request-specific settings taking precedence.
  • Enhanced the SendAsync method to pass exceptions thrown by the serializer into the RestResponse.
  • BREAKING: The regular package is no longer being signed. If you need the signed version, install PortableRest.Signed instead.

Version 2.5

  • Ability to control parameter encoding. Example: RestRequest.AddParameter("test", someStream, ParameterEncoding.Base64);.
  • Ability to add request-specific headers. This is useful in situations where the value might change between requests, for example with expiring OAuth tokens. Example: RestRequest.AddHeader("X-Authorization", yourTokenHere);
  • The RestClient will now set the UserAgent for you if you do not set the property yourself. The format will be "YourAssemblyTitleAttributeValue Major.Minor.Revision (PortableRest Major.Minor.Revision)"
  • In addition, you can call RestClient.SetUserAgent<SomeTypeFromYourRestLibrary>(someString), which in the above example would replace YourAssemblyTitleAttributeValue with the contents of someString.

Version 2.4

  • Ability to control parameter encoding. Example: RestRequest.AddParameter("test", someStream, ParameterEncoding.Base64);.
  • Ability to add request-specific headers. This is useful in situations where the value might change between requests, for example with expiring OAuth tokens. Example: RestRequest.AddHeader("X-Authorization", yourTokenHere);
  • The RestClient will now set the UserAgent for you if you do not set the property yourself. The format will be "YourAssemblyTitleAttributeValue Major.Minor.Revision (PortableRest Major.Minor.Revision)"
  • In addition, you can call RestClient.SetUserAgent<SomeTypeFromYourRestLibrary>(someString), which in the above example would replace YourAssemblyTitleAttributeValue with the contents of someString.

Quick start

Install the NuGet package: Install-Package PortableRest, clone the repo, git clone git://github.com/cloudnimble/portablerest.git, or download the latest release.

If you are planning on redistributing your own PortableRest-based client, such as our http://gaug.es Client, you need to make sure your Portable profile does not use .NET 4.0, Silverlight 4.0, or Windows Phone 7.X. Having those platforms available will cause this package to fail to install. If you need support for those platforms, create an issue and we'll investigate the possibility of adding support.

Please see the unit tests project, Bing.RestClient, or Xbox.Music for examples of how to leverage PortableRest in your REST client.

Bug tracker

Have a bug? Please create an issue here on GitHub that conforms with necolas's guidelines.

https://github.com/CloudNimble/PortableRest/issues

Twitter account

Keep up to date on announcements and more by following CloudNimble on Twitter, @CloudNimble.

Blog

Read more detailed announcements, discussions, and more on The CloudNimble Dev Blog.

Author

Robert McLaws

Copyright and license

Copyright 2018-2020 CloudNimble, Inc.

The MIT License (MIT)

Copyright (c) 2018-2020 CloudNimble, Inc. and Robert McLaws

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

  • The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.