Public contracts, how to ensure their consistency

• Does your system consist of many interconnected services?
• still manually update the service code when changing the public API?
• changes in your services often undermine the work of others, and other developers hate you for this?

Terms

What is the article about

What does the problem look like

How to solve this problem

The supplier service team will fix everything

Update the code of your service to the consumer team

Think what to do to prevent the problem from appearing

How to prevent the manifestation of a problem

1. at the design stage declaratively define contracts;
2. during implementation, we generate server and client code under contracts;
3. when testing, we check contracts and try to take into account customer needs (CDC).

How the problem looks with us

From problem to task

• server side - controllers are already written;
• the browser is a client of the service;
• Services communicate over HTTP.
• generation must be tuned. For example, to support JWT.

Questions

• which tool to choose;
• how to get contracts;
• where to place the contracts;
• where to place the client code;
• at what point to do the generation.

Which tool to choose

Tools

Tools for working with OpenAPI

Where to arrange contracts. How to access services to contracts

• Provider service project folder is the easiest option. If you need to run in the approach, then choose it.
• a shared folder is a valid option if the desired projects are in the same repository. In the long run, it will be difficult to maintain the integrity of the contracts in the folder. This may require an additional tool to account for different versions of contracts, etc.
• separate repository for specifications - if the projects are in different repositories, then the contracts should be placed in a public place. The disadvantages are the same as the shared folder.
• through the service API (swagger.ui, swaggerhub) - a separate service that deals with specification management.

At what point do you generate

Where to place the client code

• client code is close to its service and is constantly up to date;
• consumers can use the link to the project within one repository.

• will not work if you need to generate a client in another part of the system, for example, a different repository. It is solved using at least a shared folder for contracts;
• consumers must be written in the same language. If you need a client in another language, you need to use OpenApiTools.

We fasten NSwag

Controller Attributes

[Microsoft.AspNetCore.Mvc.Routing.Route("[controller]")]  //  url
[Microsoft.AspNetCore.Mvc.ApiController] //     
public class DescriptionController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("GetDescription")] //    
[Microsoft.AspNetCore.Mvc.ProducesResponseType(typeof(ConversionDescription), 200)] //    200  
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)] //    401
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)] //    403
[Microsoft.AspNetCore.Mvc.HttpGet("{pluginName}/{binaryDataId}")] //  url
public ActionResult<ConversionDescription> GetDescription(string pluginName, Guid binaryDataId) { 
 // ... 
}

[Microsoft.AspNetCore.Mvc.Route("[controller]")]
[Microsoft.AspNetCore.Mvc.ApiController]
public class FileController : ControllerBase {
[NSwag.Annotations.OpenApiOperation("SaveFile")]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(401)]
[Microsoft.AspNetCore.Mvc.ProducesResponseType(403)]
[Microsoft.AspNetCore.Mvc.HttpPost("{pluginName}/{binaryDataId}/{fileName}")]
[OurNamespace.FileUploadOperation] //  
public async Task SaveFile() { // ... }

Processor for generating specifications for file operations

• FileUploadOperationAttribute: OpenApiOperationProcessorAttribute
• FileUploadOperationProcessor: IOperationProcessor

NSwag configuration for spec and code generation

• runtime - Specifies .net runtime. For example, NetCore22;
• documentGenerator - describes how to generate a specification;
• codeGenerators - defines how to generate code according to the specification.

We generate the specification and client code when assembling the project of the service provider

1. We created a WebApi project for the client.
2. We wrote a config for Nswag CLI - Nswag.json (described in the previous section).
3. We wrote a PostBuild Target inside the csproj service provider project.

• $ (NSwagExe_Core22) run nswag.json - run the NSwag utility under .bet runtine netCore 2.2 with the nswag.json configuration

1. NSwag generates a specification from a vendor service assembly.
2. NSwag generates client code as per specification.

How to add support for JWT

protected Task<HttpRequestMessage> CreateHttpRequestMessageAsync(CancellationToken cancellationToken) {
      var message = new HttpRequestMessage();

      if (!string.IsNullOrWhiteSpace(this.AuthorizationToken)) {
        message.Headers.Authorization =
          new System.Net.Http.Headers.AuthenticationHeaderValue(BearerScheme, this.AuthorizationToken);
      }

      return Task.FromResult(message);
    }

Conclusion

• the specification is verbose;
• , ;
• ;
• .

• , URL, HTTP ..;
• OpenAPI;
• ;
• ;
• HTTP/2.

Versioning Public Contracts

Why versioning public contracts?

Solution options

Without versioning public contracts

Use versioning of public contracts

• which tool to use;
• when to introduce a new version;
• how long to maintain old versions.

Which tool to use

When to introduce a new version

• for OpenAPI there is an Azure opeanapi-diff tool for checking compatibility between 2 specifications github.com/Azure/openapi-diff;
• no automatic tool was found for gRPC, there are only versioning policies;
• general github.com/grpc/grpc/blob/master/doc/versioning.md;
• under .Net docs.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-3.1 .

How long to maintain versions

• notify customers that the old version will no longer be supported. In this case, we may lose customer income;
• support the entire set of versions. The cost of software support is growing;
• to answer this question, you need to ask the business - does the income from old customers exceed the cost of supporting older versions of software? Could it be more profitable to ask customers to upgrade?

Conclusion

Testing Contracts and CDC

Consumer driven contracts (CDC)

1. The consumer describes the contract.
2. The supplier implements this contract at home.
3. This contract is used in the CI process at the consumer and supplier. If the process is violated, then someone has ceased to comply with the contract.

Pact

1. The consumer writes tests using the PACT library.
2. These tests are converted to an artifact - pact file. It contains information about the contracts.
3. The provider and consumer use the pact file to run the tests.

Useful links about Pact

• Pact broker - pact file management solution docs.pact.io/pact_broker
• Pact does not yet support GRPC. Read more about roadmap Pact pact.canny.io .
• More information about PACT on docs.pact.io .
• Why you should use PACT docs.pact.io/faq/convinceme

How CDC can be embedded in CI

• deploying Pact + Pact broker yourself;
• purchase a ready-made Pact Flow SaaS solution.

Conclusion