Skip to content

Recommended Practices

Jump to bottom
fonlow edited this page May 31, 2017 · 1 revision

Visual Studio, WCF and ASP.NET Web API are essentially productivity tools, and there's nothing to stop you from creating .NET RESTful Web services using only a free .NET compiler and Windows Notepad.

When creating WCF Web applications and ASP.NET Web API applications, Visual Studio may create nice scaffolding codes so you may add business features, and deliver business values ASAP. However, as the system needs to evolve, the default structures of the scaffolding codes may not be adequate for managing the growing complexity.

You might need some well defined complexity (design patterns and guidelines) to manage the uncertain growing complexity.

If you have the following views/habits/preferences of designing Web API applications, you may find it is easier to use this code generator.

Keep the Web API project as thin as possible

Web services, SOAP base or RESTful are generally just a transportation for delivering server side API to the client side. It is good for team work and testing to put most if not all the business logic into the model assemblies rather than in the Web API project.

Keep Plain Old Data classes in some dedicated assemblies

Even if you are not developing a WCF application but Web API, decorating some classes with DataContractAttribute may have the following benefits:

  1. Declare/document your intention of exposing some classes to the outside worlds, and expose class properties of client only concerns.
  2. DataContract serialization is cleaner than XML serialization for POD in .NET, and the client proxy classes generated are less verbose.
  3. Comprehensive controls of namespaces on both server side and client side.
  4. Easy for code reuse at the component/assembly level.

Hints:

While using DataContractAttribute is highly recommended, however, if you have already been using JsonObjectAttribute of Newtonsoft.Json, the CodeGen could take care of it as well for cherry-picking.

Remarks

ASP.NET Web API is Microsoft's answer to the popularity of RESTful Web services. However, you could use Web API to build RESTful or RPC Web services. WebApiClientGen provides a higher abstraction for client programming, staying out a little bit off common debates/arguments/thinking of pros and cons between REST and RPC. If you construct your codebase properly, you could easily provide JSON-RPC, RESTful, HAL and SOAP Web services on the same codebase.

Clone this wiki locally