OpenStack-SDK-DotNet/DesignDetails

Overview

At a high level the design of the API is separated into four main layers (Client, POCO/Model, REST, HTTP).

Each layer is described in more detail below. By separating the API into these four levels, the API is resilient to underlying dependency changes, can be easily unit tested, and easily extended. While the end-user/consumer of the API will not see these design details, it's important for any one who would like to contribute to the project, or extend the API to be familiar with the design. Below you will find details of each layer, and how they interact.

HTTP layer

The HTTP layer is the lowest level in the API. It provides a simple abstraction for working with the HTTP protocol, and making and receiving requests and responses. While it may be considered redundant, since the .NET framwork already offers several ways to do this, HttpClient for example. There are two reason why this layer is important:

1. Unit tests can inject HTTP responses (including error states, and timeouts) without needing a live server.

By using interfaces for the abstraction, and dependency injection, unit tests can be written that inject specific HTTP responses into code that takes a dependency on this layer. This eliminates the need for an individual developer to have a live server to test against. Since remote calls are not being made, latency is greatly reduced, tests execute quickly, and the developer can continue doing what he/she does best, and not waste time on watching tests run. This does not eliminate the need for integration tests that are intended to be run against a live server. Those tests should, and will still be written, but do not need to be run as a part of a gated check-in, and should be run by the CI system on a periodic basis.

1. Tight coupling and dependencies are removed.

The .NET framework is always evolving. There are several ways (WebRequest, WebClient, HttpClient, etc) with the .NET framework alone to make a Http requests, not to mention third-party libraries. The Http layer is _not_ intended to be a replacement for these APIs. It is intended to represent a contract for the API to abstract itself from the implementation. With this layer in place, a developer that takes this layer as a dependency does not need to know or understand how the request is being carried out, if the current framework version supports the functionality required, etc. By using the Http layer, if/when the underlying implementation needs to change, none of the code that has taken a dependency will need to change (unless there is a breaking change in the Http specification, which is highly unlikely). This gives the API tremendous flexibility and allows the API to easily adapt to cross platform and framework scenarios.

REST layer

The REST layers primary responsibility is to interact with the REST endpoints of a remote service. Each service has its own REST client in this layer, that represents an interface consistent with the remote interfaces. The intention of this layer is to provide a client side representation of the remote services API surface area, and to abstract away the details of how the REST calls are formatted and made. The REST layer is responsible for taking in the required information needed by the remote service, and translating it into a request that the remote service can understand.