Software contracts are the ensamble of operation definitions and data structure used for those operations. The purpose of a contract is to establish an objective, language-agnostic description of an API, i.e., what data it accepts and returns and in which form. Contracts are used to help decoupling the development of APIs and their consumers: an API can evolve internally and change its internal behavior but, as long as it honors the established contracts, it will not break any consumer code.

DTOs

Data Transfer Objects (DTOs) are objects which only hold the data being transferred between processes. They have no behavior, except for data storing and, maybe, for serialization and deserialization.
DTOs are generated in the Contracts folder of the application project. They are normally named after the operation they are involved in, with the ‘Request’ or ‘Response’ suffix, depending on their nature. Some DTOs represent entities and do not have such suffixes: they can be used in more than one operation in order to avoid the number of DTO classes to explode while the API is being developed. They normally inherit from the EntityDTO class, which only contains the id of the entity the DTO is associated with. Entity DTOs are directly mapped against their entities, see the mapping section.

Serialization

DTOs are serialized to and deserialized from a json payload of the request/response. We adopt the following conventions:

• Property names are serialized to camel-case in json.
• The date format is "yyyy-MM-ddTHH:mm:ss.FFFZ".
• Null values are ignored, i.e., a null-valued property won’t be included in the serialized json.
• Every object is serialized with a special $type field, which is the .NET name of the object instance. This field is used by the custom client serializer so as to allow more flexibility (for example, to deserialized an abstract type from a serialized derived type).

Operations

An operation is an action that executes on the API when a request is issued to the operation’s endpoint. They are implemented over the HTTP protocol, therefore each operation is composed of an HTTP request and an HTTP response. The request is defined by its url, its HTTP verb (e.g, GET, POST, DELETE) and any possible parameter it may come with, like its request body. The response comes with an HTTP status code and, possibly, a response body. The operation’s request and response, together with their members described before, define the contract for that operation.