SDK structure and documentation

When creating new SDKs, liblab generates a folder for each language you've chosen to create an SDK for. Understanding the structure of these generated folders is critical to making the most of your SDKs. Whether you're helping end users integrate seamlessly with your API or using the SDK in your own development, knowing how everything is organized will ensure smoother implementation.

This guide provides an overview of the common elements across all SDKs created by liblab, along with language-specific details for each supported programming language.

Common SDK structure

liblab-generated SDKs follow a consistent structure across different programming languages, making it easier to work with multiple SDKs. Each SDK includes the following key components:

LICENSE

The LICENSE file outlines the SDK's licensing terms and usage guidelines, ensuring that users understand their rights and obligations when using the software.

README

The README.md file is the starting point for integrating the SDK. It provides guidance on how to get up and running with the SDK and the API it wraps. The content is customized for each SDK’s programming language, ensuring that the examples and instructions follow best practices. Typically, this file includes:

• Installation Instructions: Step-by-step guidance on how to install the SDK in your target environment.
• Authentication Setup: Instructions on setting up authentication to securely access the API.
• Sample Usage: Code snippets that show how to interact with the API, helping users quickly grasp and implement key functionality.
• Documentation Overview: Links to in-depth documentation within the SDK covering services and models that provide detailed insights into the available API resources and operations. The services documentation also features SDK code snippets for each endpoint, enabling users to quickly integrate and start using the SDK.

Documentation folder

The documentation folder is a crucial part of each SDK, containing detailed Markdown files that cover the resources and methods defined in the API specification. These files are linked from the README.md to offer basic documentation for interacting with the API via the SDK. This structure is especially beneficial when hosting your SDK on platforms like GitHub, where Markdown files are rendered for easy navigation and accessibility. The folder includes the following subfolders:

• models: Contains the API resources, representing the data structures defined in the API specification.
• services: Provides detailed documentation of the methods and operations available for each resource, guiding users on how to interact with API endpoints. This section includes SDK code snippets for every endpoint, enabling users to quickly integrate and execute API requests using the SDK.
• snippets: An optional folder that contains SDK code snippets for every API endpoint call, designed for easy integration into your existing API documentation. Depending on your configuration, this folder may include the snippets as multiple Markdown files or a single JSON file. It is generated if you configure liblab to include SDK snippets in the documentation.

Example folder

Each SDK includes an examples (or Example) folder to help you quickly get started. Inside, you'll find a simple, runnable example code demonstrating how to use the SDK to call an API endpoint. This allows you to test the SDK without having to build an application yourself.

Source Code Organization (src)

Most SDKs include a src folder or one named after the sdkName value in your liblab configuration file. This folder holds the core implementation of the SDK, organized into the following subfolders:

• models: Contains classes that represent the data structures defined in the API spec (e.g., Pet, Category).
• services: Contains classes with methods to interact with the API endpoints, aligning with the operations specified in the API spec.

Organization structure

The SDK's structure makes it easier to find and work with different SDK parts, whether adding new features or debugging existing ones.

Common SDK structures

A separate folder will be generated for each SDK language specified in your liblab configuration file. The liblab configuration file provides the following languages as examples:

C#

csharp
├── documentation
│   ├── models
│   │   ├── ApiResponse.md
│   │   ├── Category.md
│   │   ├── FindPetByStatusStatus.md
│   │   ├── Order.md
│   │   ├── Pet.md
│   │   ├── Tag.md
│   │   ├── UpdatePetWithFormRequest.md
│   │   └── UploadFileRequest.md
│   │   └── User.md
│   ├── services
│   │   ├── PetService.md
│   │   ├── StoreService.md
│   │   └── UserService.md
│   └── snippets
│       └── snippets.json
├── Example
│   ├── Example.csproj
│   └── Program.cs
├── MyEx1Sdk
│   ├── ...
│   ├── Models
│   └── Services
├── .manifest.json
├── install.sh
├── LICENSE
└── README.md

Python

python
├── documentation
│   ├── models
│   │   ├── ApiResponse.md
│   │   ├── Category.md
│   │   ├── FindPetByStatusStatus.md
│   │   ├── Order.md
│   │   ├── Pet.md
│   │   ├── Tag.md
│   │   ├── UpdatePetWithFormRequest.md
│   │   └── UploadFileRequest.md
│   │   └── User.md
│   ├── services
│   │   ├── PetService.md
│   │   ├── StoreService.md
│   │   └── UserService.md
│   └── snippets
│       └── snippets.json
├── examples
│   ├── install.cmd
│   ├── install.sh
│   └── sample.py
└── src
    └── my_ex1_sdk
        ├── models
        ├── ...
        └── services
├── .manifest.json
├── install.cmd
├── install.sh
├── LICENSE
├── pyproject.toml
└── README.md

TypeScript

typescript
├── documentation
│   ├── models
│   │   ├── ApiResponse.md
│   │   ├── Category.md
│   │   ├── FindPetByStatusStatus.md
│   │   ├── Order.md
│   │   ├── Pet.md
│   │   ├── Tag.md
│   │   ├── UpdatePetWithFormRequest.md
│   │   └── UploadFileRequest.md
│   │   └── User.md
│   ├── services
│   │   ├── PetService.md
│   │   ├── StoreService.md
│   │   └── UserService.md
│   └── snippets
│       └── snippets.json
├── examples
│   ├── src
│   │   └── index.ts
│   ├── package.json
│   ├── README.md
│   └── tsconfig.json
├── node_modules
├── src
│   └── ...
├── .manifest.json
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

GO

go
├── cmd
│   ├── examples
│   │   ├── example.go
├── documentation
│   ├── models
│   │   ├── api_response.md
│   │   ├── category.md
│   │   ├── find_pets_by_status_status.md
│   │   ├── order.md
│   │   ├── pet.md
│   │   ├── tag.md
│   │   ├── update_pet_with_form_request.md
│   │   └── upload_file_request.md
│   │   └── user.md
│   ├── services
│   │   ├── pet_service.md
│   │   ├── store_service.md
│   │   └── user_service.md
│   └── snippets
│       └── snippets.json
├── internal
│   └── ...
├── pkg
│   └── ...
├── .manifest.json
├── go.mod
├── LICENSE
└── README.md

Common SDK Structure

As outlined in the Common SDK Structure section, the following elements are consistently included in all SDKs generated by liblab:

1. Standard files like LICENSE and README.md.
2. A documentation folder with relevant subfolders.
3. An example folder containing a simple program to demonstrate the SDK in use.

liblab ensures a consistent standard for organizing code and documentation across its SDKs. As you've seen, the SDK structures for various languages share more similarities than differences, creating a unified experience. However, it's essential to understand that there are language-specific differences, which we'll dive into in the next section.

SDK Language-Specific Structures

Each programming language has its own approach to the separation of concerns (SoC), ensuring that components like data models, services, and utilities are organized according to best practices. liblab adheres to these conventions, offering SDK structures that align with the development standards of each supported language.

For example, in the Python SDK, the src/my_ex1_sdk directory contains the core SDK files, with a clear distinction between models, services, and utilities. This structure follows Python's traditional organization, enhancing maintainability and readability.

While liblab maintains a consistent structure across its SDKs, unique language conventions influence how the core code is organized. For instance, the src folder is a common convention in many languages, including Python and TypeScript, and liblab follows this naming convention when appropriate for both.

However, for languages with different naming conventions, liblab uses the sdkName property from the configuration file to name the main SDK folder, ensuring it aligns with the language's standards. For instance, PascalCase is used for C#, while snake_case is applied for Python. This approach ensures that the generated SDKs follow each language’s naming conventions, making them more intuitive and natural to work with.

C#

csharp
├── Example
├── MyEx1Sdk
│   ├── Config
│   ├── Http
│   │   ├── Handlers
│   │   └── Serialization
│   ├── Json
│   ├── Models
│   └── Services
└── documentation
    ├── models
    ├── services
    └── snippets

Python

Python's SDK structure uses both src and the value of the sdkName property from the liblab config file.

python
├── documentation
│   ├── models
│   ├── services
│   └── snippets
├── examples
└── src
    └── my_ex1_sdk
        ├── hooks
        ├── models
        │   └── utils
        ├── net
        │   ├── environment
        │   ├── headers
        │   ├── request_chain
        │   │   └── handlers
        │   └── transport
        └── services
            └── utils

TypeScript

typescript
├── documentation
│   ├── models
│   ├── services
│   └── snippets
├── examples
│   └── src
├── node_modules
└── src
    ├── http
    │   ├── handlers
    │   ├── hooks
    │   ├── serialization
    │   └── transport
    └── services
        ├── pet
        │   └── models
        ├── store
        │   └── models
        └── user
            └── models

GO

Furthermore, for Go, liblab will follow a different structure, adhering to Go's own separation of concerns (SoC) best practices:

go
├── cmd
│   └── ...
├── documentation
│   └── ...
├── internal
│   ├── clients
│   ├── configmanager
│   ├── marshal
│   ├── unmarshal
│   ├── utils
│   └── validations
├── pkg
│   ├── pet
│   ├── shared
│   ├── store
│   ├── testsdk
│   ├── testsdkconfig
│   └── user
├── .manifest.json
├── go.mod
├── LICENSE
└── README.md

By adhering to these established practices, liblab ensures that its generated SDKs are consistent and adaptable to the unique requirements of each programming language. This makes the SDKs easier to extend, modify, and integrate into your projects while maintaining alignment with the best practices and conventions of each language.