1. API versioning and documentation
Let's learn how to version and document APIs with FastAPI.
2. Why API versioning?
First of all, why would we want to version our API endpoints?
Let's return to the idea that API endpoints are like menu items.
We don't want to change any popular menu items, or else we might lose customers.
But we still want to add new options to get new customers.
Versioning lets us iterate on our API endpoints without impacting existing customers.
3. API for cloud AI jobs
Let's consider a practical example. Say we have built an API endpoint that accepts AI jobs to send to a business partner's private cloud. The v1 schema includes a job name and input data for the AI.
What if we want to add a new required field to specify the config for the AI job? If we just add the new required field, existing user requests would no longer be valid.
4. Versioned endpoints
Versioned endpoints solve this problem for us. We've prefixed our original AI job endpoint, which requires the AIJobV1 class as input, as "v1." The dot dot dot represents the rest of the function for brevity.
To add the required config field, we can simply add a new AI Job endpoint with a "v2" prefix that requires the AIJobV2 class as shown here.
5. Reasons to update endpoint version
There are two main reasons for updating endpoint versions.
The first is a breaking change in our input or output schema, as we have explored with the cloud AI job API example.
The second is a change in underlying function. For AI applications, this can often be due to updating the model code, updating the training set, or updating pre- or post-processing code.
6. Iteration with optional fields
We should also note that versioning is not always required to iterate our endpoints.
The Optional class from typing can always be used to add new optional fields to Pydantic schemas without breaking the schema. This can help us add functionality without adding a new endpoint version. As we discussed earlier in the course, Pydantic fields are defined using standard Python type hints, and this is yet another example.
7. Documenting APIs with Swagger
How can we ensure our users can keep track of endpoints and versions? FastAPI is quite good at this because it auto-generates Swagger API documentation.
Swagger is built on the OpenAPI standard, which provides standardized metadata for API endpoints. Swagger is not the only tool available for API documentation based on OpenAPI, but it is included with FastAPI as the standard.
8. Swagger UI
Here is an example of Swagger UI based on the cloud AI job API example. It shows two versioned endpoints along with the input schemas. FastAPI makes the Swagger UI available at the slash-docs endpoint, which is shown here. The OpenAPI metadata is available at /openapi.json.
9. Swagger UI for an endpoint
Expanding on an endpoint in the Swagger UI gives us more details on how to use it including a working example to try out.
10. Using FastAPI's description field
Finally, we can use FastAPI's description argument to add a header to our API docs.
11. Let's practice!
Now let's practice what we have learned about API versioning and documentation.