Skip to main content

liblab TypeScript v2 SDK generator overview

The liblab-generated TypeScript SDK is designed to help developers integrate APIs faster and with fewer errors. It automatically generates an SDK based on your API specification, reducing manual work and making the integration process smoother. In version 2 of the SDK, there are significant improvements in validation, documentation, and code clarity. The SDK now uses Zod for validation, making the SDK more secure and easier to maintain.

The SDK leverages strict typing, ensuring type safety across the entire codebase, thus reducing runtime errors. It follows a modular architecture to keep code maintainable and scalable, and makes extensive use of TypeScript’s generics to provide reusable and flexible components. Additionally, the SDK employs union types and type guards to handle complex data structures more effectively, while avoiding any type issues. This attention to TypeScript best practices not only boosts developer productivity but also improves the overall quality and stability of the integration.

Key features of liblab's TypeScript SDK​

  • Automatic SDK Generation: With liblab, you can automatically generate a TypeScript SDK for your API. This automation saves you time and effort, allowing you to focus on building your application rather than developing an SDK from scratch.

  • Integrated Documentation: The SDK includes detailed, integrated documentation that helps developers quickly understand how to use the API. In version 1, all classes, functions, and code snippets were bundled into a single README file. Version 2 improves this by providing separate, well-organized documentation for each service and model. This cleaner structure and API-specific code snippets make it easier for developers to learn and integrate the API efficiently.

  • Simplified Maintenance: You can use liblab’s github actions to incorporate SDK updates into your CI/CD pipeline. This way, every API change is synchronized with your SDK and documentation automatically. This automatic synchronization prevents compatibility issues and makes maintenance much easier and faster.

  • Error Reduction: Because the SDK is automatically generated based on your API's specification, there's a lower risk of common errors that can occur with manual implementations, including type safety and incorrectly handling return calls, resulting in less errors from the end user.

  • Faster Integration: The SDK is designed to help you integrate API functionality into your projects quickly and easily. With clear, well-structured documentation and ready-to-use code snippets for each endpoint, you can start integrating the SDK without diving into complex implementation details.

What's new in version 2?​

The transition from TypeScript SDK version 1 to version 2 brings a host of new features and improvements, including the introduction of the Zod tool, better information handling for API requests, better automatic documentation generation, and cleaner example code.

Introducing the Zod tool​

liblab's TypeScript SDK V2 introduces Zod, a powerful library for validation and typing. With Zod, you can define schemas to validate data efficiently and securely, ensuring that the data you handle always meets your standards. This reduces errors and optimizes your application's performance by preventing unnecessary API calls. The following points highlight the Zod adoption benefits:

  • Reduced Attack Surface and Lower Maintenance: By limiting dependencies to just Zod, the SDK minimizes its attack surface, lowering the risk of security vulnerabilities. Fewer dependencies also make updates and maintenance easier.

  • Enhanced Security and Reliability: Zod enforces strict input validation and type safety, helping you avoid common security issues like injection attacks.

  • Avoidance of Supply Chain Attacks: Relying on a single, well-maintained dependency like Zod significantly reduces the risk of supply chain attacks compared to using multiple third-party packages. Supply chain attacks, as the name says, are attacks seeking vulnerabilities in third party software. Most victims aren't aware of it. Requiring a single dependency only reduces the possible area for attacks, becoming easier to monitor and track possible weak points outside the code.

Enhanced information with each API request​

Version 2 provides more detailed information with each API request, including:

  • Detailed Metadata: V2 introduces a metadata section that provides comprehensive details about the request status, headers, and server information, offering more context for debugging and integration.

  • Organized Response Structure: The V2 response separates the content into data and metadata, making it easier to access information and enhancing the overall response readability.

  • Raw Data Access: The V2 response also includes a raw property, allowing direct access to the raw binary data, providing more flexibility for advanced use cases.

Default Version

Version 2 is the default version in the config file. If you want to generate the SDK in version 1 you can explicitly change it version 1 in config file before generating the SDK.

The following code blocks present examples from the same function response from each TypeScript SDK generated with liblab:

{
  sold: 1,
  string: 415,
  unavailable: 1,
  'Out Of Stock': 43,
  '{{PetStatus}}': 1,
  available: 305,
  invalid: 1,
  Error: 134,
  Available: 45,
  awaiable: 1,
  peric: 26
}

The additional information makes it easier to debug and understand the operation being performed. As a result, developers have greater visibility into data flow and API behavior, enabling quicker identification of potential issues.

Automatic documentation generation​

The new TypeScript SDK version includes a system that automatically generates more detailed documentation for the SDK's functionalities and endpoints. This feature aims to help new users adopt the SDK more quickly and to serve as a continuous resource for developers, ensuring the correct usage of the available features. In version 1, the generated documentation was provided through only one README file. In version 2, the documentation is provided in a folder organized by models and services, making it easier for developers to navigate and access the desired content. The following image displays an example of documentation organition generated with version 2.

Documentation organization

Cleaner example codes​

In version 2, we've focused on providing cleaner and more straightforward example code. The code examples have been redesigned to be more intuitive and easier to understand, regardless of a developer's experience level. This makes it easier for developers to know how to implement the SDK, speed up the development process, encourage best development practices, and contribute to creating more efficient and well-structured applications. Below, you find a comparison between a code example generated with the old TypeScript SDK and the new version 2.

### **getInventory**
Returns pet inventories by status
- HTTP Method: GET
- Endpoint: /store/inventory
**Return Type**
GetInventoryResponse
**Example Usage Code Snippet**
```Typescript
import { Testsdk } from 'testsdk';
const sdk = new Testsdk({ accessToken: process.env.TESTSDK_ACCESS_TOKEN });
(async () => {
  const result = await sdk.store.getInventory();
  console.log(result);
})();

Dev container enabled​

Now, with the V2 version, you have the option to generate dev containers for your SDK. A dev container is a development environment encapsulated within a container using technologies like Docker. This ensures consistency across different development machines. It includes everything required for the development environment. For more information, refer to the dev container page.

Set up liblab for TypeScript​

Below, you will find a quick tutorial on how to set up liblab to generate a TypeScript SDK using version 2.

Prerequisites​

To use liblab, you'll need:

1. Create the SDK​

To create TS SDKs using liblab, follow the steps below:

  1. Log into liblab:
liblab login

This will redirect you to your default browser to confirm the code in the terminal.

  1. Then, initialize liblab using your target API, as presented in the following code snippet:
liblab init --spec <OPEN_API_ADDRESS>

Note: The OpenAPI file must be in JSON or YAML format.

  1. In the Languages field, set the value to:
["Typescript"]
  1. Finally, run the command to build the project:
liblab build

2. Publish the SDK​

To use the TypeScript SDK created in your project, first, you'll need to create an npm package from your SDK. You can use this tutorial to use GitHub Actions with liblab to automate the SDK generation and publishing process and ensure that a new SDK version is generated and made available for your users after each API update.

3. Use the SDK​

After creating and publishing your TypeScript SDK npm package, your users can install the SDK using the following command:

npm install your-sdk

To import the SDK into the TypeScript project, add the following code to your TypeScript file:

import { YourSdk } from "your-sdk";

After importing, you can call any function from the SDK. The following example presents how to access the function getInventory() inside the store service.

(async () => {
  const yourSdk = new YourSdk({
    token: "YOUR_TOKEN",
  });

  const data = await yourSdk.store.getInventory();

  console.log(data);
})();

You can use the auto-generated SDK documentation to give your SDK users a complete overview of all available SDK functions.

Benefits for end users​

The enhancements in liblab's TypeScript SDK V2 make life easier for developers and deliver tangible benefits for end-users. This SDK helps ensure that your applications are reliable and responsive to the user's needs. Because the SDK simplifies and speeds up the integration process, developers can roll out new features faster. This keeps your application always updated and aligned with user expectations, enhancing overall user satisfaction.

Conclusion​

With liblab's TypeScript SDK, integrating your API has never been easier. The improvements in version 2, such as the introduction of Zod, cleaner example code, and a better automatic documentation updates, ensure that your development process is faster, safer, and more efficient. Start using the enhanced SDK today to streamline your API integration and focus on what really matters, building great applications.

Last updated on