11 posts tagged with "Changelog"

In this changelog, we're excited to announce the release of the revamped Ruby, PHP, and Swift SDKs. We've also made a change to the TypeScript SDKs to use pnpm instead of yarn or npm. This change has improved the reliability and performance of our TypeScript SDKs.

Furthermore, we've made several improvements and fixes to the Konfig's SDKs. These include various bug fixes, better documentation, security vulnerability fixes, and more rigorous testing for PHP, Python, Ruby, Go, TypeScript, and Swift SDKs.

Revamped Ruby, PHP, and Swift SDKs​

We revamped the Ruby, PHP, and Swift SDKs to be more consistent with the quality of our Python and TypeScript SDKs. This includes:

• Improved code quality
• Better test coverage
• Better documentation

In particular, we removed the array of .md files that were generated as documentation and replaced it with the singular README.md file that includes everything you need to know about the SDK. Putting everything on one page makes it easier to navigate and find what you need.

Konfig's TypeScript SDKs now use pnpm​

Based on internal quality assurance and integration tests that we regularly run on our SDKs, we found that pnpm is a better fit for our TypeScript SDKs. It's faster, more reliable, and uses less disk space than npm or yarn. The breaking point for us was concurrency bugs that were not fixable while using yarn. When switching to pnpm, we found that these issues were resolved without special configuration. This change allowed us to fix flaky tests and continually ensure our generator was working as expected.

It's been a fast start to the year and we are excited to bring you some new features and improvements to Konfig.

AI-Generated Operation IDs​

konfig fix now has a new option --useAIForOperationID that allows you to use AI to generate meaningful operation IDs for your OpenAPI specification.

As part of ensuring your OpenAPI specification is high-quality, it is important to write meaningful operation IDs. Operation IDs are used as method names in the generated SDKs. Konfig follows a strict convention for naming your operation ID. However, we understand that it can be a bit of a hassle to come up with these names. Furthermore, if you have a large OpenAPI spec, it can be a time-consuming task to name each operation ID. Now you can use AI to automate this process.

OpenAPI Specification 3.1 Support​

Konfig now supports OpenAPI Specification 3.1 🎉!

OpenAPI Specification 3.1 is the latest version of the OpenAPI Specification. It brought a few new features and improvements over the previous version, 3.0.x, but also introduced some breaking changes.

Particularly in 3.1, you can specify nullable by specifying the null keyword in the type field. This is a breaking change from 3.0.x where nullable was a separate field.

Happy New Year 🎉! We are super excited to bring you Konfig Changelog #9. We have made some improvements to the Docs Portal, fixed some security vulnerabilities and improved the Python SDK.

Docs Portal Support for iframes​

We've added support for embedding an iframe from sites such as YouTube, allowing you to embed videos and more into your portal.

Security Fixes​

We fixed a security vulnerability in our Python and TypeScript SDKs:

1. Upgraded aiohttp from 3.8.4 to 3.9.1 in Python SDK
2. Upgraded axios from 0.27.2 to 1.6.4 in TypeScript SDK

Note that both these changes are backward incompatible so if you already have SDKs with Konfig, we have put these upgrades behind a feature flag so you can upgrade at your own pace.

Improved Python SDK Type Hints​

Type hints in Python used to only previously work in PyCharm but now they work in VSCode as well.

Check Out Our New Blog Posts!​

We published two new blog posts:

1. I Reviewed 1,000s of Opinions on gRPC

These are always fun to write because I get to learn more about the general sentiment of technology and deepen my understanding of different technologies.

2. How To Implement Free, Fast, Local Search Using Fuse.js with Next.js SSR

To implement search functionality in Konfig's Docs Portal, we had to solve a really interesting problem around how to implement search in a Next.js app that is statically generated. This blog post goes into detail on how we solved this problem.

Docs Search

​

We've added a lightning fast search bar to the docs that allows you to quickly search for your docs. The search bar is available on the top right of the docs and has a shortcut of Ctrl + K to quickly focus on it (on Mac it's Cmd + K).

Inline SDK Installation Instructions​

We've added a new installation instructions section to the docs that allows you to quickly copy the SDK installation instructions for a language. This makes it easier for developers to get started with your SDKs by reducing the friction of finding the SDK installation instructions.

Google Analytics Support​

konfig.yaml

_32

outputDirectory: /tmp/acme-sdks-out

_32

specInputPath: api.yaml

_32

specPath: api-fixed.yaml

_32

portal:

_32

title: Acme

_32

primaryColor: "#1f334e"

_32

logo:

_32

light: portal-logo-light.png

_32

dark: portal-logo-dark.png

_32

googleAnalyticsId: G-XXXXXXXXXX

_32

documentation:

_32

sidebar:

_32

sections:

_32

- label: Guides

_32

links:

_32

- id: getting-started

_32

path: docs/getting-started.md

_32

- id: client-side-direct-api-usage

_32

path: docs/client-side-direct-api-usage.md

_32

demos:

_32

- id: getting-started

_32

path: demos/getting-started.md

_32

generators:

_32

python:

_32

version: 1.0.0

_32

packageName: acme_client

_32

projectName: acme-python-sdk

_32

outputDirectory: python

_32

clientName: Acme

_32

git:

_32

userId: konfig-dev

_32

repoId: acme-sdks/tree/main/python

You can now add your Google Analytics ID to your docs configuration and we'll automatically add the Google Analytics script to your docs. See the full instructions for adding Google Analytics to your docs here.

Python SDK Ergonomic Improvement​

We improved the Python SDK to return Pydantic-based response values which allows for using the __getattr__. This is slightly more concise than the previous version, which used the __getitem__ syntax to access response values.

Before​

Previously, you had to use the [] syntax to access response values. This required a little more code for every property access.

After​

With Pydantic-based response values, you can use the . syntax to access. This is slightly less verbose and looks more Pythonic.

Notice how there is also no need to use the body attribute to access the response body. All new Python SDKs will be using this new syntax.

We will not be updating previously generated Python SDKs to use this new syntax to ensure backwards compatibility.

Non-SDK Snippets in API Portal​

The API Reference page now generates non-SDK code snippets for cURL and other languages that do not have an SDK. This allows developers to quickly generate, copy, and paste code snippets regardless of whether or not there is an SDK for your language.

Improved API Portal Design

​

We completely refactored the design and look of our API Portal to be more modern, sleek, and intuitive. Take a look at the screenshots below to see the improved design. We also added generated response examples and ergonomic improvements when navigating between pages in the portal. See a full list of changes in the "Improvements and Fixes" section below.

Refactored SDK Documentation​

We now allow you to brand your README.md with a banner image using the new readmeHeader property in your konfig.yaml file like so:

This generates READMEs with your image and title at the top of the file like so:

We completely overhauled the generated documentation for Python and TypeScript to be easier to read and find what you're looking for.

We also plan to improve the generated documentation for other SDKs.

Improvements and Fixes

• API Portal now preserves scroll position when navigating between pages
• Clicking the logo in the top-left corner brings you back to homepage
• Implemented light/dark logo theme for API Portal
• Added -x to not start a mock server in konfig test
• Fix table rendering width larger than viewport in API Portal
• Fix table from causing horizontal scroll on small screens
• Fixed handling of non-Blob type values in TypeScript SDK for multipart/form-data
• Handle array type schemas in request body for API Portal
• Support bash, JavaScript, and many more languages as code blocks in API Portal
• Point top-level API Portal domain to documentation if documentation is configured
• Remove nested documentation in Python SDK
• Embed all documentation into neatly organized README.md for Python SDK
• Removed nested documentation for TypeScript SDK
• Embed all documentation into neatly organized README.md for TypeScript SDK
• Added ability to order endpoints in the API Reference page
• Fixed scrollbar blocking header on Windows for API Portal
• Fixed bug in konfig fix where fixing operation IDs fail because await wasn't used
• Fix invalid links in top-level README.md in SDK repository
• Show example values and schema in API Portal for operations

Dart​

Konfig now supports generating Dart SDKs! This means that you can now use Konfig to generate SDKs for your customer's Flutter applications or Dart projects.

Generated Python Snippets​

Konfig's API Portal now seamlessly integrates your Python SDK into the API Reference Page. This means that you can dynamically generate Python code snippets that can be easily copy-pasted for lightning-fast integration in Python. This is the second of many SDK languages that we will be integrating into Konfig.

Improved API Portal Styling​

We made improvements to the styling of the API Portal. The API portal now has rounder edges and denser styling to make it easier to read and navigate. We also made the navbar on the left side smaller to give more room for the core content on the page.

Improvements and Fixes

• Eliminated dependency security vulnerabilities in Python and TypeScript SDKs
• Add removeKonfigBranding configuration to Go SDK
• Improved generated tests and documentation for Go SDKs
• Created konfig pr-merge and konfig-pr-create commands for GitHub automation
• Fixed Git repository tagging for Go publishing to properly be indexed by pkg.go.dev
• Support submodules for Go SDK
• Created new lint rule to catch potentially invalid required syntax
• Created konfig list-sdk-submodules to be used in automation
• Support submodules in the automation pipeline
• Added client state validation in Ruby to catch invalid client state when SDK is instantiated
• Validate UUID parameters in the API Reference Page
• Created documentation for setting up API Portal with custom markdown pages
• Added --tolerate-republish flag to konfig publish to allow for gracefully publishing of existing versions
• Support multipart/form-data input for konfig mock server
• Fix bug with .yaml files not being properly pulled in konfig pull

Markdown Pages​

We are excited to announce the release of Markdown Pages! This feature allows you to create a custom documentation page for your API / SDKs. You can use markdown pages to provide examples, links to external documentation, or any other information you want to share with your users. Konfig's markdown pages are fully integrated with the rest of the portal, so you can easily create links to API endpoints or interactive demos.

Currently, we are deploying with a few early customers. If you are interested in trying it out, please reach out to [email protected].

Improvements and Fixes

• Add --ci flag to konfig fix to loosen fix rules for CI/CD automation
• Security credentials are now hidden in API Reference page
• Fixed handling of "date-time" format in API Reference page inputs
• Support array of integers / strings in API Reference page
• Support OAuth client credentials flow in API Reference page
• Support file type parameters in API Reference page
• Fixed storage of API Reference page inputs in local storage to prevent forms from other pages from being shared
• Fixed bug in Python SDK with incorrect reference to schema instead of model
• Fixed bug in setupcode for generated test_deprecation_warning.py test in Python SDK
• Fixed bug in README.md for badge in Python/TypeScript/Java SDKs when dash "-" is used
• Fixed bug in generated TypeScript code in API Reference where snake case was improperly converted to camel case

We are excited to announce the launch of our newest product at Konfig!

Introducing: API Reference

​

The Problem​

The next step after generating SDKs is adding them to your docs. But as soon as you do, something feels off. Your API reference is not integrated with your SDKs and you have to maintain two separate pages. You manually copy-paste code snippets from your SDKs to your docs and you have to update them every time your API changes. So we created a better way.

The Solution​

Introducing API Reference by Konfig. It's a single page that combines your API reference and SDKs. It's automatically generated from your OpenAPI spec and SDKs. It's always up-to-date and it's always in sync with your API. It allows you to dynamically generate code snippets for your SDKs and make API requests directly from your docs. It's a single source of truth for your API.

Currently, we are deploying with a few early customers. If you are interested in trying it out, please reach out to [email protected].

Improvements and Fixes

• Allow for configuration of a specific operation in SDK README.md files
• Remove quotes from strings when copying in demo portal
• Added "konfig versions" command to CLI to query currently published SDKs
• Add a one-time deprecation warning for deprecated operations in Python SDK

Last week we merged our plugin into Backstage (Pull Request) to generate SDKs for internal services. For those that love to follow and discuss technology, we also published a blog post where Dylan reviewed 1,000s of GraphQL vs. REST perspectives. We also made a lot of improvements to our Python, TypeScript, and PHP SDK generators.

Backstage Plugin​

SDKs help onboard external developers but we know that the same problem exists inside organizations when integrating APIs from different teams owning different services. Backstage is a developer portal for centralizing your infrastructure and enabling product teams to quickly ship high-quality code. So we created a Backstage plugin to auto-generate SDKs for internal API services. If you are interested in generating SDKs for your internal APIs please reach out to us and we would love to talk. Check out our official plugin here!

Blog Post: I Reviewed 1,000s of GraphQL vs. REST Perspectives​

Ask any developer: do you prefer GraphQL or REST? This often leads to opinionated conversations, sometimes even devolving into vulgar opinions rather than objective facts. To delve into the GraphQL vs. REST debate, I scoured platforms where developers frequently discuss such matters: YouTube, Reddit, Twitter, and Hacker News. I parsed 1,000s of discussions and synthesized my findings in this blog post, striving to present only thought-provoking perspectives. Read more here!

Improvements and Fixes

• Konfig CLI now gives a warning to update to the latest version
• Added "changeset" command for Konfig CLI to automate SDK generation using GitHub actions
• When running "konfig generate", if "specInputPath" is set then "konfig fix" is also executed
• Fix generated documentation referring to non-existent response variable in Python SDK
• Konfig CLI now always runs a mock server when running "konfig test"
• Custom package.json scripts can be added to TypeScript SDK using konfig.yaml
• Fix bug in Python SDK where unexpected keyword argument error is thrown when attaching extra properties to request bodies inside a customized SDK
• Add label to top-level README to differentiate SDKs that have PHP 7+ or PHP 8+ support (see SDK table in example README)
• Reference OpenAPI "tag" instead of "class" inside operation table in generated TypeScript SDK README
• Add flag "useDescriptionInOperationTableDocumentation" to konfig.yaml for TypeScript SDK to use "description" instead of "summary" field from operation in generated operation table for README.md
• Fix "ReadableStream" not defined in TypeScript SDK when API error is encountered in Node.js
• Improve PHP 7+ support option
• Error is now thrown if "topLevelOperations" references an operation ID that does not exist in the OAS
• Fix bug where required path parameter causes syntax issue in Python SDK
• Fix bug where dictionaries in generated Python SDK documentation was using "=" instead of ":" for dict values
• Add "konfig published" command for listing all currently published SDKs
• Add "konfig lint-python" command to run Ruff linter on Python SDK
• Fix bug in Python SDK where "_headers" is undefined
• Handle generators listed under "additionalGenerators" when using "konfig bump"