Api Client

$${\color{red}NEEDS-UPDATE}$$

Table of Contents

• Summary
• Configuration

---

Summary

Nano provides a generic api-client implementation, that can be used by other services to seamlessly connect and communicate with your micro-service. The implementation consists of an abstract BaseApi class implementation, from which the concrete and specific implementation of the micro-service can be derived. The base class provides methods for accessing all controllers and actions, using generic methods and conventions.

The constructor of the BaseApi implementation, requires an instance of ApiOptions. When deriving from a concrete implementation from BaseApi, it's automatically registered during startup as dependency and may be injected throughout the application. The ApiOptions, get resolved automatically as well, reading the values from appsettings.json. For each api create a sections, named identical to the concrete class implementation of BaseApi.

Sample Implementation

public class MyApi : DefaultApi
{
    public MyApi(ApiOptions options)
        : base(options)
    {

    }
}

It's possible to derive form the BaseApi abstract implementation, though this will leave the api-client empty, expect for any custom method implementations. Typically, this is the case when the default controller isn't used in the application, and all controller implementations are derived from BaseController.

Configuration

"MyApi": {
    "Host": "localhost",
    "Root": "api",
    "Port": 80,
    "UseSsl": false,
    "TimeoutInSeconds": 30,
    "UseExposeErrors": false,
    "UseHealthCheck": true,
    "UnhealthyStatus": "Degraded",
    "LogIn": {
      "Username": null,
      "Password": null
    }
}

Methods are available for all nano controller actions, such as finding, querying, adding, deleting and updating. Additionally, the api-client contains a custom action implementation, where both controller and action can be set at execution-time.

Authentication

Authentication happens under-the-hood, when using the api-client implementation. By default, the jwt-token of the authorization request header, is passed along. If the service being invoked, shares the same issuer, audience and secret key, the token can be used for authorization. If the endpoint is anonymous, an authentication request is first made, using the login defined in the ApiOptions, and that token is used to invoke the request. This is to ensure that if the outer service is anonymous, it allows invocations to the nested service.

Url Conventions

When Nano is building the url to invoke, the base part is made up from the properties on ApiOptions, like this.

• http({UseSsl})://{Host}:{Port}/{Root}/

The controller part, relates to the generic entity type, specified as generic type parameter, when invoking one of the api-client methods. The pluralized name of the entity is used for the name of the controller. Thus, having an model named User, the corresponding controller should be named UsersController.

Be aware, that when Nano pluralizes the name of the entity, just and 's' is appended to the name. So in order to use the api-client properly, always name your controllers like: {EntityTypeName}s.

Responses

Define a json response, and for files use either Stream or NamedStream as response.

Identity

When identity is used in the application, and one or more controllers derived from IdentityController<TEntity, TCriteria>, derived your api-client implementation from IdentityApi, to gain access to all the same methods as it's counter-part controller implementation.

Sample Implementation

public class MyApi : IdentityApi
{
    public MyApi(ApiOptions options)
        : base(options)
    {

    }
}

---