This series of blog post explains an approach to implementing ASP.NET Core Web API servers and .NET clients and provides an example implementation of a service that maps URL paths to information about corresponding entries in the Contentstack SaaS headless CMS. ASP.NET Web APIs use JSON to expose data and functionality as HTTPS services. This entry introduces ASP.NET Core Web API concepts and components, and the process of implementing an ASP.NET Core Web API.
An ASP.NET Core web API is an HTTPS service endpoint typically used to exchange JSON. A Web API server component responds to HTTP requests by serving JSON. To implement a Web API, you need to implement an action method in a class that inherits from a base controller to return JSON to the caller.
To implement a Web API service, you need to implement an action method in a web API controller. Web API action methods typically prepare a response model with properties that expose the values for the infrastructure to serialize as JSON returned to the client.
Web APIs typically accept parameters from the HTTP request, such as query string parameters. You typically implement a binding model with properties that correspond to these parameters, which the infrastructure populates and passes to your action method.
Clients can use any technology to access the Web API. If the client uses .NET, then you can implement a .NET typed client that abstracts access to the service. The client and server can share infrastructure, specifically the class that represent the JSON structure used to implement the API response contract. You likely need to implement a type to represent API configuration, such as storing the base URL of the service in appsettings.json or elsewhere.
Of these five components, only the controller is necessary. For example, it could just return a string.
- Controller: Contains our action method that implements the API to return the JSON.
- Binding Model: POCO presenting API parameters.
- Result Model: POCO representing API results
- Config: POCO for binding client configuration values from appsettings.json and elsewhere.
- Client: Abstracts calling Web API.
To process an incoming HTTP requests for a Web API, the ASP.NET MVC infrastructure uses query string parameters and other values in the request to populate a binding model of the type that your action method requires, and then passes that binding model to your action method. Your action method constructs a response model and passes that response model to the Ok() method of the ControllerBase class from which the controller that contains your action method inherits. The infrastructure serializes that response model as JSON to the response stream.
HTTPS APIs typically enforce response size limits to prevent things like unbounded queries from consuming all available computing infrastructure. The API should expose data as records rather than an individual structure. When the volume of records exceeds some page size limit, the API should return that data in pages, requiring subsequent calls to retrieve additional pages.
Deliverystack.net 
8 thoughts on “ASP.NET Core Web API Prototype, Part I: .NET Web API Server/Client Overview”