Go to content

Bulletcode.NET

API Client

Bulletcode.NET provides a built-in service for communicating with a REST API. To enable it, call the AddApiClient() extension method of IServiceCollection:

services.AddApiClient();

The ApiClientOptions class contains settings for the API client. They can be changed by passing a callback to the AddApiClient() method, or by adding a ApiClientOptions section to the appsettings.json file.

  • BaseAddress — specifies the base URL for the API.
  • Timeout — specifies the default timeout for API requests. The default value is 30 seconds.
  • HandleAcceptedResponse — when set to true, the API client automatically resends the request after receiving a response with Accepted status code. See Background Jobs for information about handling such requests on the server side. The default value is false.
  • AcceptedRetryAfter — specifies the delay after which a request is resent after receiving an Accepted response.

The API client uses the same JSON serialization options as the server; see JSON Serialization for more information.

When a request fails and the server returns an ErrorResult response, the API client throws an ErrorResultException containing the information about the error, in addition to the standard properties of the HttpRequestException. Otherwise, a plain HttpRequestException is thrown. See API Errors for more information.

IApiClient service

The IApiClient service can be used to perform requests to the API. It contains the following methods:

  • GetAsync() — performs a GET request to the given URL, with optional query string parameters, and deserializes the JSON response as an object.
  • DownloadAsync() — performs a GET request to the given URL, with optional query string parameters, and returns the response as a byte array. An optional Accept header can be passed to this method; an HttpRequestException is thrown when the content type of the server’s response doesn’t match the specified type.
  • PostAsync() — performs a POST request to the given URL. The object passed as the request body is serialized into JSON. When the result type is specified, the response is deserialized as an object of the given type; otherwise, the response is ignored.
  • PutAsync() — performs a PUT request to the given URL. This method is analogous to PostAsync().
  • UploadAsync() — performs a PUT request to the given URL, using the byte array as the request body. The content type of the request can be specified; by default, "application/octet-stream" is used. The server should be configured to access the request data for the specified content type as binary data (see MVC for more information).
  • PatchAsync() — performs a PATCH request to the given URL. This method is analogous to PostAsync().
  • DeleteAsync() — performs a DELETE request to the given URL. This method doesn’t use any request body and ignores the response body.
  • GetCustomClient() — returns a new instance of the IApiClient service with a customized HttpClient. For example, a custom Timeout can be specified.

Query string helper

The QueryStringSerializer helper class contains the following static methods for handling NameValueCollection objects:

  • Serialize() — converts an object into a NameValueCollection in such way that it can be deserialized from the query string on the server side. DateTime values are serialized using the "yyyy-MM-dd" format; enum values are serialized as numbers; null values are ignored; all other values are converted to culture invariant strings. This method is useful when performing a GET request with a complex query string.
  • ToString() — converts a NameValueCollection to a properly escaped string, including the trailing '?'. An empty string is returned if the collection is empty.

API authentication

The ApiAuthenticationService class can be used as a base class for the service which handles authentication of the API using the Token authentication mechanism. This service should call the SetToken() method in order to store the token in the ApiAuthenticationStore, and the ClearToken() method in order to clear the stored token.

The authentication token is automatically added to all requests performed using the IApiClient.

The ApiAuthenticationService periodically refreshes the token to prevent it from expiring. The abstract RefreshTokenAsync() method, which must be implemented by the inheriting class, is called in order to refresh the token. It should either call SetToken() and return true, or call ClearToken() and return false if the token couldn’t be refreshed.

The class which inherits ApiAuthenticationService should be registered as a singleton and as a hosted service, for example by calling:

services.AddHostedService( provider => provider.GetRequiredService<AccountService>() );