RestClient

Inherits: IConfigurable, IReferenceable, IOpenable

Description

The RestClient class allows you to create clients that call remote endpoints using the HTTP/REST protocol.

Configuration parameters

• base_route: base route for a remote URI
• connection(s):
  • discovery_key: (optional) key to retrieve the connection from IDiscovery
  • protocol: connection protocol (http or https)
  • host: host name or IP address
  • port: port number
  • uri: resource URI or connection string with all parameters in it
• options:
  • retries: number of retries (default: 3)
  • connect_timeout: connection timeout in milliseconds (default: 10 sec)
  • timeout: invocation timeout in milliseconds (default: 10 sec)
  • correlationId: place for adding correalationId, query - in query string, headers - in headers, both - in query and headers (default: query)

References

• *:logger:*:*:1.0 - (optional) ILogger components to pass log messages
• *:counters:*:*:1.0 - (optional) ICounters components to pass collected measurements
• *:traces:*:*:1.0 - (optional) ITracer components to record traces
• *:discovery:*:*:1.0 - (optional) IDiscovery services to resolve a connection

Fields

Instance methods

AddCorrelationId

Adds a correlation id (correlationId) to the invocation parameter map.

protected string AddCorrelationId(string route, string correlationId)

• route: string - invocation parameters.
• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• returns: string - invocation parameters with added correlation id.

AddFilterParams

Adds filter parameters (with the same name as they defined) to the invocation parameter map.

protected string AddFilterParams(string route, FilterParams filter)

• route: string - invocation parameters.
• filters: FilterParams - (optional) filter parameters.
• returns: string - invocation parameters with added filter parameters.

AddPagingParams

Adds paging parameters (skip, take, total) to an invocation parameter map.

protected string AddPagingParams(string route, PagingParams paging)

• params: string - invocation parameters.
• paging: PagingParams - (optional) paging parameters
• returns: string - invocation parameters with added paging parameters.

CallAsync

Calls a remote method via HTTP/REST protocol.

protected Task CallAsync(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route

protected Task CallAsync(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.

protected Task<T> CallAsync<T>(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• returns: Task<T> - result object

protected Task<T> CallAsync<T>(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<T> - result object

CallStringAsync

TODO: add ddescription

protected Task<string> CallStringAsync(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• returns: Task<string> - TODO: add ddescription

protected Task<string> CallStringAsync(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<string> - TODO: add ddescription

CloseAsync

Closes a component and frees used resources.

public virtual Task CloseAsync(string correlationId)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.

Configure

Configures a component by passing configuration parameters.

public virtual void Configure(ConfigParams config)

• config: ConfigParams - configuration parameters to be set.

ConstructQueryString

TODO: add description

protected string ConstructQueryString(NameValueCollection parameters)

• parameters: NameValueCollection - TODO: add description
• returns: string - TODO: add description

CreateRequestUri

TODO: add description

protected Uri CreateRequestUri(string route)

• route: string - TODO: add description
• returns: Uri - TODO: add description

CreateEntityContent

TODO: add description

protected HttpContent CreateEntityContent(object value)

• value: object - TODO: add description
• returns: HttpContent - TODO: add description

ExecuteAsync

Executes a remote method via the HTTP/REST protocol.

protected Task ExecuteAsync(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.

protected async Task<T> ExecuteAsync<T>(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<T> - result object.

protected Task<T> ExecuteAsync<T>(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<T> - result object.

ExecuteStringAsync

TODO: add description

protected Task<string> ExecuteStringAsync(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• returns: Task<string> - TODO: add description

protected Task<string> ExecuteStringAsync(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• returns: Task<string> - TODO: add description

Instrument

Adds instrumentation to log calls and measures call time. It returns a Timing object that is used to end the time measurement.

protected CounterTiming Instrument(string correlationId, [CallerMemberName]string methodName = null)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• methodName: [CallerMemberName]string - method name.
• returns: CounterTiming - CounterTiming object used to end the time measurement.

InstrumentError

Adds instrumentation to error handling.

protected void InstrumentError(string correlationId, [CallerMemberName]string methodName = null, Exception ex = null, bool rethrow = false)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• methodName: [CallerMemberName]string - method name.
• ex: Exception - Error that occured during the method call.
• rethrow: bool - true to throw the exception.

IsOpen

Checks if the component is open.

public virtual bool IsOpen()

• returns: bool - true if the component is open and false otherwise.

OpenAsync

Opens the component.

public virtual Task OpenAsync(string correlationId)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.

SetReferences

Sets references to dependent components.

public virtual void SetReferences(IReferences references)

• references: IReferences - references used to locate the component’s dependencies.

SafeExecuteAsync

Safely executes a remote method via HTTP/REST protocol and logs execution time.

protected Task<T> SafeExecuteAsync<T>(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<T> - result object.

protected async Task<T> SafeExecuteAsync<T>(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “get”, “head”, “post”, “put”, “delete”
• route: string - command route. Base route will be added to this route
• returns: Task<T> - result object.

SafeCallAsync

Safely calls a remote method via the HTTP/REST protocol and logs execution time.

protected Task<T> SafeCallAsync<T>(string correlationId, HttpMethod method, string route, object requestEntity)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “post”, “put”, “patch”.
• route: string - command route. Base route will be added to this route
• requestEntity: object - request body object.
• returns: Task<T> - result object.

protected Task<T> SafeCallAsync<T>(string correlationId, HttpMethod method, string route)

• correlationId: string - (optional) transaction id used to trace execution through the call chain.
• method: HttpMethod - HTTP method: “post”, “put”, “patch”.
• route: string - command route. Base route will be added to this route
• returns: Task<T> - result object.

Examples

class MyRestClient: RestClient, IMyClient 
{
    ...

    public MyData GetData(string correlationId, string id)
    {
        var timing = this.Instrument(correlationId, 'myclient.get_data');
        try
        {
            var result = this.ExecuteAsync<MyData>(correlationId, HttpMethod.Post, "/get_data", new MyData(id));
        }
        catch (Exception ex)
        {
            this.InstrumentError(correlationId, "myclient.get_data", ex, true);
        }
        finally
        {
            timing.EndTiming();
        }
        return result;        
    }
    ...
}

var client = new MyRestClient();
client.Configure(ConfigParams.FromTuples(
    "connection.protocol", "http",
    "connection.host", "localhost",
    "connection.port", 8080 ));

var data = client.GetData("123", "1");
...

See also

• RestService

• CommandableHttpService