New fields for client code snippets

[baywet]

One of the main scenarios to use OpenAPI is to generate documentation for humans to read.

The specification does a great job at describing all the aspects to craft the HTTP request, and deal with the HTTP response. It also provides "places" to provide examples for both (example, and examples fields). Those are great when using "barebone" HTTP clients on the platform, and crafting payloads manually.

However, more often than not, the API producer may also provide SDKs, or want to provide end to end code snippets for a given operation with the native client for the platform.

I propose that we create such a place so people don't have to rely on extensions for such things! (could be in a SAF as well, depending on where the SAF discussion goes). Here is a quick example

openapi: 3.3.0
paths:
  "/foo":
    get:
      content:
        "application/json":
           schema:
             type: object
             # the usual stuff
           # this part is new
           snippets:
             "shell/curl": |
               curl "/foo"
             "python/httpx": |
               import httpx
               httpx.get('https://www.example.org/')
             "csharp/kiota;v=1": |
               using MyClient;
               var client = new MyClient(new AnonymousAuthenticationProvider());
               await client.Foo.GetAsync();

Here a couple of things are interesting:

The snippets entry is at the media type level, this is to account for operations that support multiple media types (e.g. json vs event stream) which would require different client code.

The language part (shell, python, csharp) in the entries would rely on a registry we operate, since there doesn't seem to be an registry for programming languages other than implementations that are specific to platforms (e.g. linguist for GitHub)

The client part (curl, httpx, kiota) could either be another registry, or "free" for anybody to use as they which.

The version part is optional, and can be used in case multiple versions of the same client are being supported/showcased.

Thoughts?

[ralfhandl]

Just off the top of my head:

• Isn’t that something that LLMs can generate from an OAD?
• Should the field be named clientCodeSnippets?
• Do we need a registry for client languages?

[baywet]

yes, you can generate them for trivial operations, but the quality varies, and for more complex operations sometimes a handcrafted snippet it more illustrative.
sure, we can debate the better name, I don't have any strong preference either way.

the reason why I'm bringing a registry is to enable better interoperability between the descriptions and tools. Obviously we don't want to end up a couple of years down the road with descriptions containing C#, CSharp, C-Sharp, CS, etc... And I couldn't find one that is "administered" (RFC, IANA, etc...) and not implementation specific (like GitHub Linguist)

[lornajane]

We could formalise x-codeSamples since it seems to be fairly widely adopted. Or is there something about the "in the wild" implementation that you particularly wanted to avoid, @baywet ?

[baywet]

For others context this is an example of such extension

One of the challenges I'm seeing is the interoperability of the "languages" between platforms (c.f. my reply to Ralf), hence my proposition to pair this with some kind of registry.

Other than that, I'm pretty open on the actual structure as long as we can:

• define different snippets for different media types (because they need different code to be handled)
• define multiple variants for the same language (because any language might have multiple http clients)

[baywet]

I did put together a proposal for the registry OAI/spec.openapis.org#104

[karenetheridge]

I feel like this belongs in the Example Object, rather than at a higher level such as in Operation.

[baywet]

Since it's tied to the object model at the media type level that would certainly work.

[handrews]

We've also had repeated requests to support whole-operation examples. I'm too lazy to look it up right now, but I would favor adding it in 3.3.

[handrews]

There is already at least one vendor extension, x-snippets (at the Operation level) from Stainless that does this. And as noted in another comment Speakeasy has x-codesamples.

[baywet]

Interesting, we've been working with them for the OpenAI SDKs, and in that context they use x-oaiMeta in the specifications which look something like this:
(at the operation level)

      x-oaiMeta:
        name: List assistants
        group: assistants
        examples:
          request:
            curl: |
              curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer $OPENAI_API_KEY" \
                -H "OpenAI-Beta: assistants=v2"
            python: |-
              import os
              from openai import OpenAI

              client = OpenAI(
                  api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
              )
              page = client.beta.assistants.list()
              page = page.data[0]
              print(page.id)
            javascript: |-
              import OpenAI from "openai";

              const openai = new OpenAI();

              async function main() {
                const myAssistants = await openai.beta.assistants.list({
                  order: "desc",
                  limit: "20",
                });

                console.log(myAssistants.data);
              }

              main();
            node.js: |-
              import OpenAI from 'openai';

              const client = new OpenAI({
                apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
              });

              // Automatically fetches more pages as needed.
              for await (const assistant of client.beta.assistants.list()) {
                console.log(assistant.id);
              }
            go: |
              package main

              import (
              	"context"
              	"fmt"

              	"github.com/openai/openai-go"
              	"github.com/openai/openai-go/option"
              )

              func main() {
              	client := openai.NewClient(
              		option.WithAPIKey("My API Key"),
              	)
              	page, err := client.Beta.Assistants.List(context.TODO(), openai.BetaAssistantListParams{})
              	if err != nil {
              		panic(err.Error())
              	}
              	fmt.Printf("%+v
              ", page)
              }
            java: |-
              package com.openai.example;

              import com.openai.client.OpenAIClient;
              import com.openai.client.okhttp.OpenAIOkHttpClient;
              import com.openai.models.beta.assistants.AssistantListPage;
              import com.openai.models.beta.assistants.AssistantListParams;

              public final class Main {
                  private Main() {}

                  public static void main(String[] args) {
                      OpenAIClient client = OpenAIOkHttpClient.fromEnv();

                      AssistantListPage page = client.beta().assistants().list();
                  }
              }
            ruby: |-
              require "openai"

              openai = OpenAI::Client.new(api_key: "My API Key")

              page = openai.beta.assistants.list

              puts(page)

[karenetheridge]

After looking over this again (and especially at the examples, seeing code embedded in the OAD itself, are you kidding me???!), I'm not convinced this belongs in the OAD at all. The entire point of an OAD is to describe an API thoroughly enough that client code could be created from it that generates a compliant API request. So isn't this something that a vendor tool would provide, either by generating snippets such as these up front or creating the request on demand using OAD data? If I were an API engineer writing an API client against an OAD, I wouldn't be storing my code or scripts in the OAD itself -- I'd do it in separate files and index the interfaces by operation id, because I'd want the code/scripts to be tailored to my specific local environment (using an API gateway, proxy) and authentication keys.

tldr: I don't see how publishing this information in the OAD itself would be very interoperable: it's taking the existing generic nature of the OAD and making it less generic for a local environment.

[lornajane]

I'm also leaning in this direction, perhaps we could encourage the existing implementations to add their usage to the registry and leave it there?

[baywet]

While I understand this point of view from the perspective of reasonably sized teams, it breaks down for larger organizations.

Essentially in our use case, we have dozens of teams, and multiple pipelines contributing to the OpenAPI description which powers SDK generation, reference docs generation, server-side code generation, etc...
That service description is the result of:

1. Ingestion of partner descriptions to TypeSpec (we sim-ship/augment the API surface of partner companies)
2. Authoring of additional TypeSpec definitions by about a dozen internal teams (additional APIs, additional properties on existing API surface....)
3. Generation of "basic" snippets (here is how you call this specific operation), work in progress.
4. Authoring of "scenario" snippets (here is how this operation fits in the broader context), work in progress. (these live on a repository, and would then be re-injected in the description through some automation)

At each of these steps, the description is being augmented by different teams to add information. Some additions are vertical (e.g. the team responsible for the evaluations APIs build the evaluation related scenarios snippets), some are horizontal (e.g. the developer experience team generates all the basic snippets, because they have expertise about the SDKs).

What's really important in all of that, is the use of a single asset to then power all these experiences. We come from a place with partial and incomplete descriptions that are all over the place, and that breaks down. (from teams thinking they have the same API definition but it's actually slightly different, to entire aspects, like the snippets, missing from some of the variants)

Foundry is not alone with this kind of challenge. While we've decided to enable the authoring experience with TypeSpec and the tooling with OpenAPI, Microsoft Graph is doing similar aggregation and alignment with CSDL (which delivered a terrible authoring experience) and from that derives an OpenAPI description to power a lot of the tooling. Yes, in that second example the code snippets were not in the description itself, but arguably that was a missing, it meant that the embedded doc for the SDK didn't contain ANY example, forcing the end user to get out of the IDE.

If this demand is "too specific to megacorps", I understand, and we'll go ahead with our own extension. But I feel like we might not be the only ones with that challenge and that it was worth at least having a discussion on the topic :)

[lornajane]

I don't think it's specific to any organisation size or type, I just don't think the code to interface with the API needs to be part of the OpenAPI description which describes the interface. I think using one of the existing extensions (and getting a good description of it and the various language keys, etc) into the registry would be the best next step for this feature.