DigitalOcean has unveiled an exciting new development in its suite of tools designed to empower developers by simplifying cloud computing and artificial intelligence. Staying true to its mission, DigitalOcean has been actively working to make its services more accessible to developers worldwide, ensuring that they can interact with DigitalOcean resources using their preferred programming languages. The latest addition in this endeavor is the introduction of DoTs, a TypeScript SDK that promises to enhance the way developers manage their DigitalOcean resources.
A Brief Overview of DigitalOcean’s Developer Tools
DigitalOcean’s journey in providing developer-friendly tools began with the launch of GoDo, a Software Development Kit (SDK) for the Go programming language. This was followed by PyDo, a Python SDK, effectively broadening its reach to include more programming ecosystems. Now, with DoTs, DigitalOcean aims to leverage the strengths of TypeScript, a language that has become a game-changer in modern software development.
Why TypeScript?
TypeScript has emerged as a popular choice among developers for building large-scale, complex applications. Its introduction of static type checking allows developers to catch errors early in the development process, long before these issues can impact production environments. This proactive error detection significantly enhances the reliability and maintainability of codebases. Moreover, TypeScript offers an array of features like intelligent code completion, inline documentation, and clear error highlighting within Integrated Development Environments (IDEs), making the development process smoother and more efficient.
The Evolution of SDK Development
Traditionally, creating SDKs for new ecosystems required a significant amount of manual effort, including writing repetitive code in different programming languages. This approach was not only labor-intensive but also prone to human errors. However, the advent of automated code generation has revolutionized SDK development. It allows companies to deliver consistent, high-quality SDKs across various languages with minimal manual intervention.
DigitalOcean leverages OpenAPI, a specification that defines the structure of the API, along with GitHub Actions to automate the entire SDK development process. This includes validating the OpenAPI specifications, generating client code using Kiota, and publishing the generated client documentation. This automation ensures that the SDK remains up-to-date with the latest API changes, providing a seamless experience for developers.
Engineering Requirements for the TypeScript SDK
To ensure the TypeScript SDK is easy to deploy, maintain, and update, several engineering requirements were established:
- Client Generation: The client should be automatically generated from the OpenAPI 3.0 Specification.
- Automated Testing: Testing for client generation is fully automated and integrated into the Continuous Integration (CI) pipeline.
- Automated Documentation: The documentation for client generation is automatically created and hosted on Read the Docs.
- CI/CD Support: An automated workflow was implemented to keep DoTs in sync with the latest DigitalOcean OpenAPI 3.0 Specification.
Understanding Kiota
Kiota is an open-source API client code generator developed by Microsoft. It transforms OpenAPI specifications into strongly typed SDKs in various languages, including TypeScript, Python, and C#. Kiota simplifies SDK code generation by parsing OpenAPI descriptions using the Microsoft.OpenApi.NET library. This library efficiently handles large-scale API definitions, constructing a hierarchical URI space tree from PathItems to enable readable and scalable code generation.
Kiota employs a language-agnostic code model instead of traditional templates, ensuring consistency across languages and reducing maintenance complexity. The generated code connects to core libraries via Kiota abstractions, facilitating HTTP requests without dependence on specific HTTP client libraries. This ensures flexibility and a consistent developer experience.
For those interested in delving deeper into Kiota’s design and functionality, the official Kiota documentation provides comprehensive insights.
Implementing Authentication in Kiota
One of the key features of Kiota is its flexible and modular approach to client authentication. Developers can seamlessly integrate various authentication mechanisms through the AuthenticationProvider interface. This design allows for custom logic to authenticate HTTP requests, accommodating different authentication strategies such as API keys, OAuth tokens, or custom headers.
To authenticate a client in Kiota, developers must implement the AuthenticationProvider interface. This interface defines a method, authenticateRequest, responsible for adding authentication details to outgoing HTTP requests. For instance, an API key-based authentication provider adds an Authorization header with the API key to each request, ensuring secure communication with the API.
Setting Up the Client
Once the authentication provider is implemented, it can be passed to the Kiota-generated client during initialization. The client can then make secure API requests, such as creating a DigitalOcean Droplet via the /v2/droplets endpoint.
Creating a DigitalOcean Droplet and Attaching a Volume
To create a Droplet and attach a volume using the DoTs SDK, developers can follow a series of steps involving importing necessary modules, setting up authentication, and executing API calls. This process includes finding SSH key fingerprints, creating Droplet requests, and attaching volumes to Droplets, demonstrating the powerful capabilities of the SDK.
Automated Testing
To ensure the reliability and stability of the DoTs SDK, every commit to the repository undergoes rigorous Continuous Integration workflows. This involves running code linters for style validation, implementing mocked and integration tests using Jest, and verifying that the client behaves as expected.
- Mocked Tests: These tests ensure that the generated client contains all the expected classes and methods for the corresponding API resources and operations. They focus on individual operations using mocked responses, making them fast and efficient to run.
- Integration Tests: Integration tests replicate real-world scenarios where a customer interacts with the API through the client. These tests require a valid API token and create actual resources on the associated DigitalOcean account, ensuring the client behaves as expected in production-like environments.
Automated Documentation
One of the significant advantages of generating a client from a single source of truth, such as the OpenAPI 3.0 specification, is the ability to produce documentation that is always aligned with the generated client. For DoTs, TypeDoc is used to create up-to-date documentation, which is then hosted on Read the Docs. This ensures developers have access to accurate and comprehensive references for the client without requiring manual updates.
CI/CD Integration: Keeping the Client Up-to-Date
To ensure the DoTs SDK remains current, the code generation process is automated using GitHub Actions. Changes in the OpenAPI repository automatically trigger the generation of libraries and their deployment to the DoTs repository.
Kiota Behavior
Kiota applies several transformations to API responses to ensure consistency and prevent conflicts:
- Parameter Case Conversion: Kiota automatically converts parameters from snake_case to camelCase when generating API requests, aligning with TypeScript’s conventions.
- Reserved Keyword Handling: To avoid conflicts with reserved keywords, Kiota modifies them during code generation. For instance, a property like
default: trueis transformed todefaultEscaped: true.Known Issues
Kiota currently generates nested value fields for nested arrays, a known issue by design. More information about this issue can be found on the Kiota GitHub repository.
Conclusion
The launch of DoTs represents a significant enhancement in DigitalOcean’s efforts to provide developers with efficient, streamlined tools for interacting with their APIs. By leveraging Kiota for client generation, automated workflows, and robust testing, DigitalOcean has built a solution that prioritizes reliability, scalability, and ease of use. Developers are encouraged to explore DoTs and experience how it simplifies their development workflows. Feedback is always welcome as DigitalOcean continues to refine and improve its offerings.
For more information, you can refer to the original announcement and resources available on DigitalOcean’s official blog.
For more Information, Refer to this article.
