Skip to content

Commit 1e2c6cb

Browse files
ShigermanShigerman
authored
improve documentation-14 (#320)
1 parent 34e220c commit 1e2c6cb

File tree

5 files changed

+55
-55
lines changed

5 files changed

+55
-55
lines changed

‎docs/concepts/api_version_parameter.md‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
# API Version Parameter
1+
# API version parameter
22

3-
Cadwyn adds another routing layer to FastAPI by default: by version parameter. This means that before FastAPI tries to route us to the correct route, Cadwyn will first decide on which version of the route to use based on a version parameter. Feel free to look at the example app with URL path version prefixes and arbitrary strings as versions [here](../how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md).
3+
Cadwyn adds another routing layer to FastAPI by default: by a version parameter. This means that before FastAPI selects the correct route for the request, Cadwyn decides which version of the route will be used based on the version parameter. Feel free to look at the example app with URL path version prefixes and arbitrary strings as versions [here](../how_to/version_with_paths_and_numbers_instead_of_headers_and_dates.md).
44

5-
## API Version location
5+
## API version location
66

7-
The version parameter can be passed in two different ways:
7+
A version parameter can be passed in two different ways:
88

9-
- As a custom header
10-
- As a URL path parameter
9+
- as a custom header
10+
- as a URL path parameter
1111

12-
Cadwyn will use the following defaults:
12+
Cadwyn uses the following defaults:
1313

1414
```python
1515
from cadwyn import Cadwyn, Version, VersionBundle
@@ -45,12 +45,12 @@ app = Cadwyn(
4545
)
4646
```
4747

48-
## API Version format
48+
## API version format
4949

50-
The version parameter can be formatted in two different ways:
50+
A version parameter can be formatted in two different ways:
5151

52-
- As an ISO date
53-
- As an arbitrary string
52+
- as an ISO date
53+
- as an arbitrary string
5454

5555
Cadwyn uses the following default:
5656

@@ -63,7 +63,7 @@ app = Cadwyn(
6363
)
6464
```
6565

66-
In the example above only dates will be accepted as valid versions.
66+
In the example above only dates are accepted as valid versions.
6767

6868
You can also use an arbitrary string:
6969

@@ -80,21 +80,21 @@ app = Cadwyn(
8080
)
8181
```
8282

83-
In the example above any string will be accepted as a valid version. Arbitrary strings can be used, Cadwyn will not sort them. Cadwyn will assume their actual order matches the order of the versions in the `VersionBundle`.
83+
In the example above any arbitrary string is accepted as a valid version. Cadwyn does not sort them, Cadwyn assumes that their actual order matches the order of the versions in the `VersionBundle`.
8484

85-
### API Version waterfalling
85+
### API version waterfalling
8686

87-
For historical reasons, date-based routing also supports waterfalling the requests to the closest earlier version of the API if the request date parameter doesn't match any of the versions exactly.
87+
For historical reasons, date-based routing also supports waterfalling the requests to the closest earlier version of the API if the request date parameter does not match any of the versions exactly.
8888

8989
If the app has two versions: 2022-01-02 and 2022-01-05, and the request date parameter is 2022-01-03, then the request will be routed to the 2022-01-02 version, as it is the closest version, but lower than the request date parameter.
9090

91-
An exact match is always preferred to a partial match and a request will never be matched to the higher-versioned route.
91+
An exact match is always preferred to a partial match and a request is never matched to the higher-versioned route.
9292

93-
We implement routing like this because Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. For example, imagine that you have two Cadwyn services: Payables and Receivables, each defining its own API versions. Payables service might contain 10 versions while Receivables service might contain only 2 versions because it didn't need as many breaking changes. If a client requests a version that does not exist in Receivables, we will waterfall to some earlier version, making Receivables behavior consistent even if API keeps getting new versions.
93+
The routing is implemented like this because Cadwyn was born in a microservice architecture and it is extremely convenient to have waterfalling there. Assume that you have two Cadwyn services: Payables and Receivables, each defining its own API versions. Payables service might have ten versions while Receivables service might have only two versions because it did not need as many breaking changes. If a client requests a version that does not exist in Receivables, Cadwyn will waterfall to some earlier version, making Receivables behavior consistent even if API keeps getting new versions.
9494

95-
## API Version Parameter Title and Description
95+
## API version parameter title and description
9696

97-
You can pass a title and/or a description to the `Cadwyn` constructor. It is equivalent to passing `title` and `description` to `fastapi.Path` or `fastapi.Header` constructors.
97+
You can pass a title and/or a description to the `Cadwyn()` constructor. It is equivalent to passing `title` and `description` to `fastapi.Path()` or `fastapi.Header()` constructors.
9898

9999
```python
100100
app = Cadwyn(
@@ -104,8 +104,8 @@ app = Cadwyn(
104104
)
105105
```
106106

107-
## API Version Context Variables
107+
## API version context variables
108108

109-
Cadwyn automatically converts your data to a correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
109+
Cadwyn automatically converts your data to the correct version and has "version checks" when dealing with side effects as described in [the section above](./version_changes.md#version-changes-with-side-effects). It can only do so using a special [context variable](https://docs.python.org/3/library/contextvars.html) that stores the current API version.
110110

111-
You can also pass a different compatible contextvar to your `cadwyn.VersionBundle` constructor.
111+
You can also pass a different compatible `contextvar` to your `cadwyn.VersionBundle()` constructor.

‎docs/concepts/beware_of_data_versioning.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Beware of data versioning
22

3-
Often you will want to introduce a breaking change where one of the following is true:
3+
Often you may want to introduce a breaking change when one of the following is true:
44

55
* Old data cannot be automatically converted to the structure of the new response
66
* New response cannot be automatically migrated to an older response
77
* Old request cannot be automatically converted to the HEAD request
88

9-
This means that you are not versioning your API, you are versioning your **data**. This cannot be solved by an API versioning framework. It also makes it incredibly hard to version as you now cannot guarantee compatibility between versions. Avoid this at all costs -- all your API versions must be compatible between each other. Data versioning is not a result of a complicated use case, it is a result of **errors** when divising a new version. I am yet to meet a single case where data versioning is the right way to solve an API versioning problem.
9+
This means that you are not versioning your API, you are versioning your **data**. Such an issue cannot be solved using an API versioning framework. It also makes it incredibly hard to version as you now cannot guarantee compatibility between versions. Avoid this at all costs — all your API versions must be compatible between each other. Data versioning is not a result of a complicated use case, it is a result of **errors** when devising a new version. I have yet to see a single case where data versioning is the right way to solve an API versioning issue.

‎docs/concepts/changelogs.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# Changelogs
22

3-
Cadwyn can automatically generate API changelogs for your versions. By default they are available through the unversioned endpoint `GET /changelog`. You can also get it from `Cadwyn.generate_changelog` method.
3+
Cadwyn can automatically generate API changelogs for your versions. By default, they are available through the unversioned endpoint `GET /changelog`. You can also access it via `Cadwyn.generate_changelog()` method.
44

55
## Hiding version changes and instructions
66

7-
Sometimes you might want to do private internal version changes or instructions within the version changes that should not be visible to the public. You can do this by using the `cadwyn.hidden` function. For example:
7+
Sometimes you might want to make private internal version changes or instructions within the version changes that should not be visible to the public. You can do this by using the `cadwyn.hidden()` function. Consider the example below:
88

99
```python
10-
from cadwyn import hidden, VersionChange, endpoint
10+
from cadwyn import VersionChange, endpoint, hidden
1111

1212

1313
class VersionChangeWithOneHiddenInstruction(VersionChange):
@@ -35,4 +35,4 @@ If you want to delete the changelog endpoint, pass `changelog_url=None` to `Cadw
3535

3636
## Changelog structure and entry types
3737

38-
Please, visit the swagger page for your app and check the structure and values of enums in the `/changelog` endpoint.
38+
Please visit the Swagger page for your app and check the structure and values of enums in the `/changelog` endpoint.

‎docs/theory/references.md‎

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,51 @@
1-
# Literature
1+
# References
22

3-
During Cadwyn's development, I went through countless resources on API Versioning. The following are the most unique and effective ones I managed to find.
3+
While developing Cadwyn, I went through countless resources on API versioning. The following are the most unique and helpful ones I managed to find.
44

5-
## Cadwyn-like API Versioning
5+
## Cadwyn-style API versioning
66

77
### Articles
88

9-
* [API Versioning at Stripe](https://stripe.com/blog/api-versioning)
10-
* [API Versioning at Intercom](https://www.intercom.com/blog/api-versioning/)
11-
* [Rolling Versions at Convoy](https://getconvoy.io/blog/rolling-versions)
12-
* [Breaking Things Without Breaking Things at Keygen](https://keygen.sh/blog/breaking-things-without-breaking-things/)
13-
* [API Versioning at LinkedIn Marketing](https://engineering.linkedin.com/blog/2022/-under-the-hood--how-we-built-api-versioning-for-linkedin-market)
9+
* [API versioning at Stripe](https://stripe.com/blog/api-versioning)
10+
* [API versioning at Intercom](https://www.intercom.com/blog/api-versioning/)
11+
* [Rolling versions at Convoy](https://getconvoy.io/blog/rolling-versions)
12+
* [Breaking things without breaking things at Keygen](https://keygen.sh/blog/breaking-things-without-breaking-things/)
13+
* [API versioning at LinkedIn Marketing](https://engineering.linkedin.com/blog/2022/-under-the-hood--how-we-built-api-versioning-for-linkedin-market)
1414

1515
### Projects
1616

1717
#### Python
1818

19-
* [Django REST Framework Versioning](https://github.com/binnev/djangorestframework_versioning)
19+
* [Django REST framework versioning](https://github.com/binnev/djangorestframework_versioning)
2020

2121
#### Golang
2222

2323
* [Pinned](https://github.com/sjkaliski/pinned)
24-
* [Request Migrations for Go](https://github.com/subomi/requestmigrations) (by the author of Convoy)
24+
* [Request migrations for Go](https://github.com/subomi/requestmigrations) (by the author of Convoy)
2525

2626
#### Ruby
2727

2828
* [Gates](https://github.com/phillbaker/gates)
29-
* [Request Migrations for Ruby](https://github.com/keygen-sh/request_migrations)
29+
* [Request migrations for Ruby](https://github.com/keygen-sh/request_migrations)
3030

3131
#### PHP
3232

33-
* [Laravel API Migrations](https://github.com/lukepolo/laravel-api-migrations)
34-
* [Request Migrations for PHP](https://github.com/tomschlick/request-migrations)
33+
* [Laravel API migrations](https://github.com/lukepolo/laravel-api-migrations)
34+
* [Request migrations for PHP](https://github.com/tomschlick/request-migrations)
3535

36-
## Overview articles on API Versioning
36+
## Overview articles on API versioning
3737

3838
* [Developing an API](https://smartlogic.io/blog/2012-12-12-developing-an-api/)
3939
* [API versioning has no right way](https://apisyouwonthate.com/blog/api-versioning-has-no-right-way/)
40-
* [The tricks of API Versioning](https://thenewstack.io/tricks-api-versioning/)
41-
* [Versioning API in Django REST Framework](https://studygyaan.com/django/versioning-api-in-django-rest-framework)
42-
43-
## Other articles on API Versioning
44-
45-
* [Postman API Platform: API Versioning](https://www.postman.com/api-platform/api-versioning/)
46-
* [Four REST API Versioning Strategies](https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies)
47-
* [The Ultimate Guide to Microservices Versioning Best Practices](https://www.opslevel.com/resources/the-ultimate-guide-to-microservices-versioning-best-practices)
48-
* [ASP.NET API Versioning on GitHub](https://github.com/dotnet/aspnet-api-versioning)
49-
* [API Versioning at SuperJob](https://habr.com/ru/companies/superjob/articles/577650/)
50-
* [Better API Versioning with Semantic Versioning in Django REST Framework](https://mikehelmick.medium.com/django-rest-framework-better-api-versioning-with-semantic-versioning-d93908613dea)
51-
* [How Badoo Versions its API for internal clients](https://youtu.be/M2KCu0Oq3JE)
40+
* [The tricks of API versioning](https://thenewstack.io/tricks-api-versioning/)
41+
* [Versioning API in Django REST framework](https://studygyaan.com/django/versioning-api-in-django-rest-framework)
42+
43+
## Other articles on API versioning
44+
45+
* [Postman API Platform: API versioning](https://www.postman.com/api-platform/api-versioning/)
46+
* [Four REST API versioning strategies](https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies)
47+
* [The ultimate guide to microservices versioning: best practices](https://www.opslevel.com/resources/the-ultimate-guide-to-microservices-versioning-best-practices)
48+
* [ASP.NET API versioning on GitHub](https://github.com/dotnet/aspnet-api-versioning)
49+
* [API versioning at SuperJob](https://habr.com/ru/companies/superjob/articles/577650/)
50+
* [Better API versioning with semantic versioning in Django REST framework](https://mikehelmick.medium.com/django-rest-framework-better-api-versioning-with-semantic-versioning-d93908613dea)
51+
* [How Badoo versions its API for internal clients](https://youtu.be/M2KCu0Oq3JE)

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ nav:
133133
- "Changelog": "home/CHANGELOG.md"
134134
- "Theory":
135135
- "How we got here": "theory/how_we_got_here.md"
136-
- "Literature": "theory/literature.md"
136+
- "References": "theory/references.md"
137137
- "How to build a versioning framework": "theory/how_to_build_versioning_framework.md"
138138

139139
watch:

0 commit comments

Comments
 (0)