Make generated APIs easier to work with

[DanielMSchmidt]

TL;DR

Move from positional arguments to object arguments for the sake of readability and extendability

Details

The API that is currently generated is quite hard read if one has to fill in a property that is not the first or second argument.

The current function signature is like this (on the example of namespaces)

export class CoreV1Api {
    public async createNamespace (body: V1Namespace, pretty?: string, dryRun?: string, fieldManager?: string, options: {headers: {[name: string]: string}} = {headers: {}}) : Promise<{ response: http.IncomingMessage; body: V1Namespace;  }>{}
	public async listNamespace (pretty?: string, allowWatchBookmarks?: boolean, _continue?: string, 	fieldSelector?: string, labelSelector?: string, limit?: number, resourceVersion?: string, timeoutSeconds?: number, watch?: boolean, options: {headers: {[name: string]: string}} = {headers: {}}) : Promise<{ response: http.IncomingMessage; body: V1NamespaceList;  }> {}
}

This leads to calls like this api.createNamespace(namespace, undefined, true, undefined, {headers: {TRACE_REQUEST: "1"}}), which are hard to understand / reason about without looking into the client itself.

I would like to propose a different format:

// These types would be exported by the package and imported in this file
type Options = {
  pretty?: string
  dryRun?: string
  options?: {headers: {[name: string]: string}}
}
type Result<T> =  Promise<{ response: http.IncomingMessage; body: T;  }>

type CreateOptions<T> = Options & {
  body: T
  fieldManager?: string,
}
type CreateFunction<T> = (opts: CreateOptions<T>) => CreateResult<T>

type ListOptions = Options & {
	allowWatchBookmarks?: boolean
	_continue?: string
	fieldSelector?: string
	labelSelector?: string
	limit?: number
	resourceVersion?: string
	timeoutSeconds?: number
	watch?: boolean
}
type ListFunction<T> = (opts: ListOptions) => Result<V1NamespaceList>


// The generated file begins here
export class CoreV1Api {
    public async createNamespace (opts: CreateOptions<T>): CreateResult<T>{}
	public async listNamespace (opts: ListOptions) : Result<V1NamespaceList> {}
	// ...
}

This would allow us to call the api in a readable way: api.createNamespace({body: namespace, dryRun: true, options: {headers: {TRACE_REQUEST: "1"}}). Someone without intimate knowledge of the client library can instantly understand this.

Another benefit of having an object as configuration is that it easier to extend / change without breaking clients and that a user can define their own abstractions. For example defining a function that adds a header is a very different experience after we implement this:

type ListFn<T> = (pretty?: string, allowWatchBookmarks?: boolean, _continue?: string, 	fieldSelector?: string, labelSelector?: string, limit?: number, resourceVersion?: string, timeoutSeconds?: number, watch?: boolean, options: {headers: {[name: string]: string}} = {headers: {}}) : Promise<{ response: http.IncomingMessage; body: V1NamespaceList;) => T
function addHeader<T>(fn: ListFn<T> | CreateFn<T> | ...): T {
  if (isListFn(fn)) {
    return (pretty?: string, allowWatchBookmarks?: boolean, _continue?: string, 	fieldSelector?: string, labelSelector?: string, limit?: number, resourceVersion?: string, timeoutSeconds?: number, watch?: boolean, options: {headers: {[name: string]: string}} = {headers: {}}): T => fn(pretty, allowWatchBookmarks, _continue, fieldSelector, labelSelector, limit, resourceVersion, timeoutSeconds, watch, {...options, headers: {...options.headers, myHeader: "is there"})
  }

  if (isCreateFn(fn)){ .... }
}

// Versus after this change

function addHeader<T extends Options, R>(fn: (opts: T) => R): (opts: T) => R {
	return (opts) => fn({...opts, options: {...opts.options, headers: {...opts.options.headers, myHeader: "is there"}})
}

[brendandburns]

All of this code comes from the openapi code generator (typescript-node). If we want to make changes, the changes need to be made there.

Though for what it's worth, we need to also change away from the request generator, since the request library is deprecated.

[DanielMSchmidt]

I can take a look and tackle those issues 👍

[jgehrcke]

@DanielMSchmidt small world :-) Hope you're good!

we need to also change away from the request generator, since the request library is deprecated.

Yes! And whichever HTTP client we choose (I think I can recommend got by now, also for its timeout control) we need to find a way to expose HTTP client options in a generic and yet TypeScript-supported way. Related: #544

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-contributor-experience at kubernetes/community.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-contributor-experience at kubernetes/community.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[Maistho]

/reopen
/remove-lifecycle rotten

This is still very much relevant.

[k8s-ci-robot]

@Maistho: You can't reopen an issue/PR unless you authored it or you are a collaborator.

In response to this:

/reopen
/remove-lifecycle rotten

This is still very much relevant.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[drubin]

/reopen

[k8s-ci-robot]

@drubin: Reopened this issue.

In response to this:

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[drubin]

@brendandburns I am not sure how to tackle this but It think moving away from request lib should be done as its been deprecated for ages.

Do you think we can assign that to you?

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[arash-bizcover]

/remove-lifecycle rotten

[theomessin]

Could we not just switch over to typescript-fetch? It'd be two birds with one stone since it uses an options object instead of positional arguments (OpenAPITools/openapi-generator#569).

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[theomessin]

/remove-lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[arash-bizcover]

/remove-lifecycle rotten

[arash-bizcover]

/remove-lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue.

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[Maistho]

/reopen

/remove-lifecycle rotten

[k8s-ci-robot]

@Maistho: You can't reopen an issue/PR unless you authored it or you are a collaborator.

In response to this:

/reopen

/remove-lifecycle rotten

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.