Eve.NET

Eve.NET is a simple HTTP and REST client for Web Services powered by the Eve Framework. 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 of operating systems and .NET Platforms.

Usage

Initialization

// 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

// Returns a List<T>.
var companies = await client.GetAsync<Company>();

Assert.AreEqual(HttpStatusCode.OK, client.HttpResponse.StatusCode);
Assert.AreEqual(companies.Count, 10);

// Returns a List<T> which only includes changed items since a DateTime.
var ifModifiedSince = DateTime.Now.AddDays(-1);
var companies = await client.GetAsync<Company>(ifModifiedSince);

Assert.AreEqual(HttpStatusCode.OK, client.HttpResponse.StatusCode);
Assert.AreEqual(companies.Count, 2);

GET at Document Endpoints

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>(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<Company>("companies", companyId, eTag);

// HttpStatusCode is still 'NotModified'.
Assert.AreEqual(HttpStatusCode.NotModified, client.HttpResponse.StatusCode);

POST/Create Requests

var company = await client.PostAsync<Company>(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<DateTime>(company.Created);
Assert.IsInstanceOf<DateTime>(company.Updated);
Assert.IsNotNullOrEmpty(company.UniqueId);
Assert.IsNotNullOrEmpty(company.ETag);

PUT/Replace Requests

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>(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

// 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

// 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

// 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<T> requests, 
// exposed by the HttpResponse property.

Installation

Eve.NET is on NuGet. 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 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 for details.

License

Eve.NET is a Nicola Iarocci and Gestionali Amica open source project, distributed under the BSD license.