fastapi-icontract 0.0.1

Benefits of Adding Contracts to Your API

Enforcing code contracts in your FastAPI development opens up new venues for approaches to more systematic design at the API level:

• Contracts are an important part of the specification.

  Unlike human language, contracts written in code are unambiguous.

• Contracts are automatically verifiable.

  Your clients can rest assured that you actually run them. FastAPI-icontract will specify precisely which contracts are run in production and which were only verified during testing.

• Contracts provide deeper testing.

  If you have a mesh of microservices that you need to test in conjunction, turn on all the contracts and test against your client’s data instead of your own limited unit test data.

• Contracts specified in code allow for automatic client-side verification.

  Thus you can signal formally to the client up-front what you expect (using pre-conditions), while the client can verify what to expect back from you (using post-conditions).

• Contracts are not just for input validation.

  Though you can use contracts for input validation as well, FastAPI already allows you to specify how you want your input verified. Contracts, on the other hand, really shine when you want to specify relations between the endpoints.

• Contracts allow for automatic test generation.

  Tools for property-based testing such as Schemathesis can automatically generate test data and verify that your API works as expected. Post-conditions are an easy way to define your properties to be tested.

  There is an ongoing discussion with the authors of the Schemathesis how to integrate it with tools which generate data based on contracts such as icontract-hypothesis.

• Contracts open up a wider ecosystem for analysis.

  When you decorate the endpoints with contracts, you can immediately use analysis tools such as CrossHair to analyze your code and find bugs.

  (Though this only makes sense for really stateless, purely functional endpoints.)

Teaser

The full documentation is available at: fastapi-icontract.readthedocs.io.

The following example is meant to invite you to further explore the extension.

Versioning

We follow Semantic Versioning. The version X.Y.Z indicates:

• X is the major version (backward-incompatible),

• Y is the minor version (backward-compatible), and

• Z is the patch version (backward-compatible bug fix).