Explore best practices for developing and managing your Web API using REST principles. This guide covers essential topics such as serialization of view models, documentation, versioning, and returning appropriate response codes.
When building a simple API based on Entity Framework, It can be tempting to keep it simple and bind persistent entities directly to WebAPI output.
Documenting your WebAPI is important but you don't want to spend a massive amount of time trying to keep documentation up to date. The solution is to use Swaggerand Swashbuckle.
When integrating with external Web APIs which return a JSON response, there is a quick and easy way to generate classes to handle that response.
When creating WebAPIs for your applications, it is useful to keep the naming consistent all the way from the back-end to the front-end.
You can save time and reduce human error by automatically generating clients for your APIs.
As an API provider, one of your most important tasks is to make sure that breaking changes will never occur in your API. Making breaking changes will make life difficult for the developers who depend on your service and can easily start causing frustration when things start to break.
When the Web API creates a resource, it should include the URI of the new resource in the Location header of the response.
Good error design is as important to the success of an API as the API design itself. A good error message provides context and visibility on how to troubleshoot and resolve issues at critical times.
The use of correct response codes is a simple yet crucial step towards building a better WebAPI. In ASP.NET Core, by default the WebAPI framework sets the response status code to 200 (OK), regardless of whether the task succeed or an error occurred.
You can save yourself countless hours of painful debugging , by specifying the correct response code.
Client-side validation provides a great user experience but this must always be backed up by server-side validation.
- Do you serialize View Models (aka DTOs), not Domain Entities?
- Do you document your Web API?
- Do you know how to easily get classes from a JSON response?
- Do you know that WebAPI and table names should be consistent?
- Do you know the best way to generate your classes from swagger?
- Do you provide versioning?
- Do you return a Resource URL?
- Do you return detailed error messages?
- Do you return the correct response code?
- Do you use Fluent Validation?
- Do you know the key principles of REST API Design?