The Interledger Community 🌱

Cover image for Ruby Language Support for Kiota — ILF Grant Final Report
Andrea Peruffo
Andrea Peruffo

Posted on

Ruby Language Support for Kiota — ILF Grant Final Report

Brief Project Description

Kiota is Microsoft's open source tool that generates ready-to-use API clients from an OpenAPI description. Its Ruby support was Experimental: the generated code often failed on real APIs, only JSON was supported, and the Ruby libraries it relies on were spread across several repositories. This grant closed those gaps, with the Open Payments APIs as the reference use case. All the work is merged upstream, and Ruby moved to Preview on November 10, 2026, the last day of the grant. The progress report covers the first two months.

Project Update

The grant ran from August 10 to November 10, 2026, on the original timeline. Every objective in the proposal is done, across 54 merged pull requests in nine repositories, all linked at the end. The first two months ended with the first payment sent through Open Payments using only Kiota-generated Ruby clients. The last month closed the remaining gaps:

  • More data formats. Generated Ruby clients now handle every format Kiota supports (JSON, plain text, forms and file uploads), not only JSON.
  • Change tracking. After asking the community (kiota#8440), I completed this feature, which lets a client send only the values that changed.
  • Clearer errors and deprecation warnings. Errors show the API's own message, and clients warn when they use parts of an API that are being retired.
  • Tested on real APIs. Ruby is now tested against all 22 API descriptions in Kiota's test suite, including GitHub, Stripe, Twilio, DocuSign, Notion and Microsoft Graph, with none excluded.
  • Request URLs. I fixed a bug in std-uritemplate, the library Kiota uses to build request URLs and which I maintain, that dropped characters from some URLs in Ruby and three other languages.
  • Documentation. There is a Ruby quickstart on Microsoft Learn, with a matching sample.
  • Releases. The seven Ruby libraries were released five times since the progress report, up to version 0.25.3.
  • Preview. Based on Kiota's language maturity criteria, I proposed moving Ruby from Experimental to Preview in kiota#8572, and the maintainers merged it on November 10.

Open Payments, end to end

The demo sends a payment through Open Payments with clients that Kiota generates from the official Open Payments API descriptions. Only two small parts are written by hand: the payment flow itself, and the request signing that Open Payments requires. It uses only released versions of Kiota and the Ruby libraries, and it runs either on its own or on the Interledger test network. The README has the instructions.

Sending real payments was also the best test: it found bugs that the unit tests had missed, such as a value sent in the wrong format that made the server reject every request. All of them are fixed in Kiota.

Project Impact & Target Audience(s)

The direct beneficiaries are Ruby developers who want a ready-to-use client for an API without writing it by hand, and the Interledger ecosystem in particular. Interledger publishes Open Payments SDKs for Node, PHP, Go, Rust, Python, .NET and Java, but not for Ruby. Before this work, generating one with Kiota was not an option either, because its Ruby output often failed on real APIs. A community member opened kiota#7956 asking for exactly that. Today a Ruby team can generate an Open Payments client with a released Kiota and start from the quickstart. This lowers the barrier for Rails and Ruby teams to integrate Open Payments, which supports the Foundation's mission of broadening who can build on the Interledger Protocol.

The wider Kiota and std-uritemplate communities benefit too: several fixes landed in Kiota's core and help every language it supports, and the URL fix also reaches Python, Swift and Dart users.

The project does not target a specific demographic group. The work is upstream, open source (MIT) and free to use, so anyone can benefit from it without a relationship to me or to the Foundation.

Progress on Objectives, Key Activities

Final status against the proposal, grouped as in the original submission.

Critical fixes

Objective Status Links
Binary/stream type support Done. kiota#8256, kiota#8265, kiota-ruby#163
HTTP send method dispatch (void, collection, collection of primitives) Done. kiota-ruby#155, kiota#8256
Text, Form and Multipart serialization gems Done. Three new libraries, released in 0.25.0. kiota-ruby#177, kiota-ruby#178, kiota-ruby#179, kiota#8443
Triage the integration test suppressions Done. The main integration test passes and no tests are excluded. kiota#8116, kiota#8127, kiota#8131, kiota#8255, kiota#8301, kiota#8502

High-severity gaps

Objective Status Links
Composed types (union/intersection) Done. kiota#8065, kiota#8209, kiota#8314, kiota-ruby#106, kiota-ruby#142, kiota-ruby#151, kiota-ruby#171
Backing store (complete or remove) Done, completed after asking the community. kiota#8440, kiota-ruby#176, kiota#8442
Scalar vs parsable request body discrimination Done. kiota-ruby#158, kiota#8256
Unit test coverage Done. Ruby generator tests went from 74 to 181, more than Python's 138.

Completeness and quality

Objective Status Links
Enum handling (collections, defaults by wire name, wire values) Done. kiota#8053, kiota#8256, kiota#8314, kiota-ruby#158
Typed errors, status code and headers on ApiError Done. kiota-ruby#153, kiota-ruby#171
Idiomatic Ruby output Done. The generated code follows Ruby conventions and passes the standard Ruby linter. kiota#8037, kiota#8052, kiota#8301, kiota#8531
Unset scalars left off the wire Done. kiota-ruby#154
Primary error message Done. kiota#8348
Deprecation annotations Done. Documentation tags and optional runtime warnings. kiota#8476, kiota#8477
Runtime gem stabilization toward 1.0 Done. Seven libraries in one repository with automated releases, from version 0.16.0 to 0.25.3 during the grant. kiota-ruby#112, kiota-ruby#140, v0.25.3
Quickstart documentation Done. Ruby quickstart on Microsoft Learn, with a sample. quickstart, openapi-docs#178, kiota-samples#9278, kiota#8501
Maturity from Experimental toward Preview Done. Ruby is a Preview language since November 10, 2026. kiota#8572

All the work is merged upstream, except a small fix to the VS Code extension's Ruby defaults (kiota#8500), which is waiting for review.

Communications and Marketing

All of the work happened in public on GitHub, through pull requests, reviews and issue threads with the Kiota maintainers.

  • Public summary: posted on kiota#7956, the issue that motivated the Open Payments use case.
  • Grant lightning talk: a short talk on the results, recording: https://drive.google.com/file/d/1J6FSu6ZJNlQGzCL2PHK1mUbgdZW63p-4/view?usp=sharing
  • Documentation: the Ruby quickstart on Microsoft Learn is the public entry point for Ruby users, and the Open Payments demo shows the full payment flow.
  • Kiota Discord: I discussed direction with the Kiota team there throughout the grant.

The proposal has no marketing budget.

What's Next?

Ruby is now in Preview, and the next step is to hear from the people using it: what works, what is missing, and what matters most on the way to a stable release. That feedback will shape where Ruby support goes from here.

The community is already moving: within days of the grant ending, a contributor added automatic retries and redirects to the Ruby HTTP library. The few known gaps are tracked as issues on microsoft/kiota-ruby.

Community Support

  • Try it. If you write Ruby, try the quickstart with an API you use, or the Open Payments demo, and share what works and what doesn't on microsoft/kiota-ruby.
  • Contribute. The open issues on microsoft/kiota-ruby are a good way into Kiota.
  • Is a Ruby Open Payments SDK wanted? The generated clients could be the basis of an official Ruby SDK, next to the existing ones. I would welcome a conversation with the Open Payments team about whether that is desirable.

Additional Comments

Thanks to Vincent Biret @vincentbiret_216 for reviewing every pull request promptly and for the guidance on the Preview proposal.

As stated in the proposal, AI tooling (Claude Code) was used throughout for analysis and implementation, with every change reviewed by me before it was submitted and then by the Kiota maintainers before it was merged.

Relevant Links/Resources (optional)

Generator pull requests, microsoft/kiota:

Runtime pull requests, microsoft/kiota-ruby:

Former per-gem repositories, before the consolidation:

URI templates, std-uritemplate:

Documentation and samples:

Open at the end of the grant:

Core fix benefiting all languages, from a community contributor: https://github.com/microsoft/kiota/pull/8193

Top comments (0)