Fstop Python SDK
The Fstop Python SDK was the last project I built as part of Beyond the Docs. I wanted to understand how SDKs are generated, how they relate to OpenAPI specifications (OAS), and what role they play in the overall developer experience.
The Fstop Python SDK is auto-generated from the OpenAPI specification using Speakeasy.
How I built it​
Honestly...I didn't "build" the SDK in the traditional sense. Speakeasy built it for me.
After I decided that I wanted to build an SDK for the Fstop API, I did some research and discovered that Speakeasy is a popular SDK generation tool. I installed the CLI, made sure my OAS file was in good shape, ran Speakeasy, and out came a fully functional Python SDK.
It was interesting to watch the API transform into a Python library. Endpoints became Python methods, request and response models became Python classes, and operation summaries and descriptions became docstrings. Everything came from the OAS file.
What I learned​
A good SDK starts with a good OpenAPI specification​
Before this project, I mostly thought of an OAS file as something used to generate API reference documentation. Building the SDK changed that perspective.
I learned that the OAS becomes the source of truth for much more than documentation. Speakeasy used it to generate Python functions, request and response models, parameter descriptions, and docstrings. The SDK's quality is directly tied to the quality of the specification, so spending time writing clear operation summaries, descriptions, and examples is important.
SDK documentation looks different from API documentation​
While researching SDKs, I noticed that companies take different approaches to documenting them. Some publish dedicated SDK reference documentation, while others rely on generated code examples, docstrings, or documentation platforms that generate examples in multiple languages.
I decided not to create separate SDK reference documentation for this project. Instead, I included Python SDK examples in the feature guides.
Another thing I learned from building an SDK is that documentation isn't just feature guides. Docstrings are also a form of documentation, as they document the Python code and describe parameters and return values.
Tech stack​
- Speakeasy for SDK generation
- Python