.NET Web API SDK Architecture

A Software Development Kit (SDK) is a set of development tools that help when creating applications for a particular platform. A web API SDK is a SDK that provides tools to help consume a particular web (HTTP) based API and encapsulates all the required domain logic to communicate with the API.

SDKs are typically provided in the form of a library or package that a consuming application can reference and use. For example in .NET a SDK that consumes a public web API could be provided as a NuGet package which is then used from a particular application.

The following describes a proposed simple architecture to follow when creating .NET based SDKs for a particular web based API. Though the focus of this architecture is .NET other object-oriented development environments should also easily map to it.

Types (classes) involved in the architecture of an web API SDK.

Each box in the diagram above represents a type (class), or set of types. Together IClient, ClientConfig, and the Contract Request/Response types represent the entire public “interface” of the SDK.

Main SDK types:

• Client is the main class that communicates with the API and implements the IClient interface. This is the class that will provide methods that relate to operations on the API.
• IClient is the interface to use Client. The consuming application’s code should be coupled to this.
• ClientConfig represents any settings for the Client class. This could include API endpoint URIs, API login details etc. An instance of this type should most likely be injected in to the Client on initialisation.
• Contract Request/Response Types represents the request (input) and response (output) types for the various supported operations from IClient/Client.
• RequestFactory is responsible for creating .NET HttpRequestMessage objects based on any incoming Contract Request object.
• ResponseHandler is responsible for taking the incoming .NET HttpResponseMessage from the API, handling any errors, serializing the response content etc. and returning a Contract Response object.

Code Example

The following C# code demonstrates an example use of the types defined above from within a Client type that communicates with an imaginary web based customer API:

SDK C# code for communicating with an imaginary customer API