REST API Communication

API Consumption

When creating code that will consume a REST API, a client using System.Net.Http.HttpClient SHOULD be used. REST wrapper nuget packages like RESTSharp SHOULD NOT be used.

Any sensitive API keys or necessary information to protect security MUST use proper configuration management techniques. See Configuration for more information.

Consider using IHttpClientFactory and typed clients. See the Microsoft Documentation for implementation patterns.

Framework

For creating REST APIs, the ASP.NET Core framework SHOULD be used.

Authorization

API authorization MUST be handled using MarksNelson.IdentityServer.

Definition and Discovery

Documentation for REST APIs SHOULD be made available. Swagger / OpenAPI initiative (http://swagger.io/) and Swashbuckle (https://github.com/domaindrivendev/Swashbuckle) SHOULD be used.

If the intended consumer of the API is the general public, or some potentially unknown consumers in the future, full documentation, including some simple examples, MUST be included for all endpoints that are created.

For internal developers or client developers, basic documentation including endpoints SHOULD be available. Full descriptions and write ups are not necessary unless the usage is not obvious based on the signature.

Versioning

To ensure proper servicing of multiple clients that are using API endpoints we wish to modify or deprecate, API endpoints MUST begin from a Base URL that contains a version identifier.

e.g., https://<host>/api/v1/<resource path>, https://<host>/api/v2/<resource path>

This allows APIs to remain backward compatible when publishing updates.

When modifying the API spec that would bring in a breaking change, the version number of the API MUST be updated. Previous versions of the API MUST remain operational. Your project’s code architecture SHOULD account for this change to take place at some point in the future, but API versions SHOULD NOT be updated frequently.

Once you have a breaking change and have consumers of a production endpoint, you MUST add a new version.

Content Type

JSON SHOULD be the content type published by your API.

Beginning in .NET Core 3.0, you SHOULD use System.Text.Json and the new built-in support. For earlier versions of .NET Core and .NET framework projects, the Newtonsoft.JSON serializer that ships with Web API SHOULD be used.