https://github.com/pyeve/eve.net
Portable HTTP and REST Client for Web Services powered by the Eve Framework
https://github.com/pyeve/eve.net
Last synced: 5 months ago
JSON representation
Portable HTTP and REST Client for Web Services powered by the Eve Framework
- Host: GitHub
- URL: https://github.com/pyeve/eve.net
- Owner: pyeve
- License: other
- Created: 2014-11-24T15:26:50.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2018-04-26T13:49:21.000Z (over 7 years ago)
- Last Synced: 2025-08-01T08:49:48.835Z (5 months ago)
- Language: C#
- Homepage: http://python-eve.org
- Size: 205 KB
- Stars: 21
- Watchers: 4
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES
- License: LICENSE
Awesome Lists containing this project
README
Eve.NET [](https://ci.appveyor.com/project/nicolaiarocci/eve-net)
=======
Eve.NET is a simple HTTP and REST client for Web Services powered by the [Eve
Framework][1]. It leverages both `System.Net.HttpClient` and `Json.NET` to
provide the best possible Eve experience on the .NET platform.
Cross platform
--------------
Eve.NET is delivered as a .NET Standard 1.1 package, which makes it compatible
with a [wide range][10] of operating systems and .NET Platforms.
Usage
-----
### Initialization
```C#
// Simplest initialization possible.
var client = new EveClient();
client.BaseAddress = new Uri("http://api.com");
// or
var client = new EveClient { BaseAddress = new Uri("http://api.com") };
// or!
var client = new EveClient {
BaseAddress = new Uri("http://api.com"),
BasicAuthenticator = new BasicAuthenticator ("user", "pw")
};
// Set target resouce for subsequent requests.
client.ResourceName = "companies";
````
### GET at Resource Endpoints
```C#
// Returns a List.
var companies = await client.GetAsync();
Assert.AreEqual(HttpStatusCode.OK, client.HttpResponse.StatusCode);
Assert.AreEqual(companies.Count, 10);
// Returns a List which only includes changed items since a DateTime.
var ifModifiedSince = DateTime.Now.AddDays(-1);
var companies = await client.GetAsync(ifModifiedSince);
Assert.AreEqual(HttpStatusCode.OK, client.HttpResponse.StatusCode);
Assert.AreEqual(companies.Count, 2);
```
### GET at Document Endpoints
```C#
var company = companies[0];
// Update an existing object silently performing a If-None-Match request based
// on object ETag. See http://python-eve.org/features#conditional-requests
company = await client.GetAsync(company);
// StatusCode is 'NotModified' since ETag matches the one on the server (no
// download was performed). Would be OK if a download happened. Object did not
// change.
Assert.AreEqual(HttpStatusCode.NotModified, client.HttpResponse.StatusCode);
// Raw, conditional GET request
var companyId = "507c7f79bcf86cd7994f6c0e";
var eTag = "7776cdb01f44354af8bfa4db0c56eebcb1378975";
var company = await client.GetAsync("companies", companyId, eTag);
// HttpStatusCode is still 'NotModified'.
Assert.AreEqual(HttpStatusCode.NotModified, client.HttpResponse.StatusCode);
```
### POST/Create Requests
```C#
var company = await client.PostAsync(new Company { Name = "MyCompany" });
// HttpStatusCode is 'Created'.
Assert.AreEqual(HttpStatusCode.Created, client.HttpResponse.StatusCode);
Assert.AreEqual("MyCompany", company.Name);
// Newly created object includes properly initialized API metafields.
Assert.IsInstanceOf(company.Created);
Assert.IsInstanceOf(company.Updated);
Assert.IsNotNullOrEmpty(company.UniqueId);
Assert.IsNotNullOrEmpty(company.ETag);
```
### PUT/Replace Requests
```C#
company.Name = "YourCompany";
// PUT requests will silently perform a If-Match request so server copy will only be
// updated if server and document ETag match.
// See http://python-eve.org/features#data-integrity-and-concurrency-control
var result = await client.PutAsync(company);
Assert.AreEqual(HttpStatusCode.OK, client.HttpResponse.StatusCode);
Assert.AreEqual(result.Name, company.Name);
// UniqueId and Created did not change.
Assert.AreEqual(result.UniqueId, company.UniqueId);
Assert.AreEqual(result.Created, company.Created);
// However Updated and ETag have been updated.
Assert.AreNotEqual(result.Updated, company.Updated);
Assert.AreNotEqual(result.ETag, company.ETag);
```
### DELETE Requests
```C#
// DELETE requests will silently perform a If-Match request so document
// will only be deleted if its ETag matches the one on the server.
// See http://python-eve.org/features#data-integrity-and-concurrency-control
var message = await client.DeleteAsync(Original);
Assert.AreEqual(HttpStatusCode.OK, message.StatusCode);
```
### Mapping JSON and Eve meta-fields to Classes
```C#
// You want to map Eve meta-fields to class properties by flagging them with
// the RemoteAttribute. Since these are usually consistent across API
// endpoints it is probably a good idea to provide a base class for your
// business objects to inherit from.
public abstract class BaseClass
{
[JsonProperty("_id")]
[Remote(Meta.DocumentId)]
public string UniqueId { get; set; }
[JsonProperty("_etag")]
[Remote(Meta.ETag)]
public string ETag { get; set; }
[JsonProperty("_updated")]
[Remote(Meta.LastUpdated)]
public DateTime Updated { get; set; }
[JsonProperty("_created")]
[Remote(Meta.DateCreated)]
public DateTime Created { get; set; }
}
By default, snake_case conversion will be adopted when (de)serializing classes to json.
For example, `MyClass.ThisIsAProperty` will be serialized to `this_is_a_property` in
the json. If you want to change this behaviour, set the `ContractResolver` property
accordingly.
```
### Raw GET Requests
```C#
// You can use this method to perform parametrized queries.
var query = @"companies?where={""n"": ""MyCompany""}";
// GetAsync will return a HttpResponseMessage which you can freely inspect.
var response = await client.GetAsyc(query);
Assert.AreEqual(HttpStatusCode.OK, result.StatusCode);
Assert.AreEqual("application/json", result.Content.Headers.ContentType.ToString())
// Please note that you also get the HttpResponseMessage object with GetAsync requests,
// exposed by the HttpResponse property.
```
Installation
------------
Eve.NET is on [NuGet][9]. Run the following command on the Package Manager Console:
```
PM> Install-Package Eve.NET
```
Or install via the NuGet Package Manager in Visual/Xamarin Studio.
Running the tests
-----------------
You are supposed to clone the [`evenet-testbed`][7] repo and run a local
instance of the test webservice. Alternatively, if you don't have a Python/Eve
environmnet at hand, you can opt to rely on a free (and slow, and very resource
limited) test instance which is available online. See [tests code][8] for
details.
License
-------
Eve.NET is a [Nicola Iarocci][2] and [Gestionali Amica][3] open source project,
distributed under the [BSD license][4].
[1]: http://python-eve.org
[2]: http://nicolaiarocci.com
[3]: http://gestionaleamica.com
[4]: https://github.com/pyeve/Eve.NET/blob/master/LICENSE.txt
[5]: http://msdn.microsoft.com/en-us/library/system.net.http.httpclient%28v=vs.118%29.aspx
[6]: http://james.newtonking.com/json
[7]: https://github.com/pyeve/Eve.NET-testbed
[8]: https://github.com/pyeve/Eve.NET/blob/master/Eve.Client.Tests/MethodsBase.cs#L13-L31
[9]: https://www.nuget.org/packages/Eve.NET/
[10]: https://docs.microsoft.com/en-us/dotnet/standard/net-standard