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)

[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?