Client operations with interface ...Res vs struct *...OK

[yowayb]

First, my hands thank the Maintainers for handling this boilerplate! Second, I ran ogen on the Pinterest spec and it generated 116 client methods as expected. However, 93 of them return a *Res interface, while 23 of them return a pointer *...OK struct. Moreover, one of the methods returning an (unexpected) pointer *...OK struct works correctly, while another method returning an (expected) ...Res interface fails with:

./main.go:33:34: res.GetItems undefined (type api.CampaignsListRes has no field or method GetItems)

Here's my code:

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	"fuzzytuxedomedia.com/pintryst/api"
)

func run(ctx context.Context) error {
    sec := Auth{}
    client, err := api.NewClient("https://api.pinterest.com/v5/", sec)
    if err != nil {
        return fmt.Errorf("create client: %w", err)
    }

    res, err := client.AdAccountsList(ctx, api.AdAccountsListParams{})
    if err != nil {
        panic(err)
    }

    for _, account := range res.GetItems() {
        params := api.CampaignsListParams{
        	AdAccountID: account.ID.Value,
        }

        res, err := client.CampaignsList(ctx, params)
        if err != nil {
            panic(err)
        }
        for _, item := range res.GetItems() {
            fmt.Printf("item: %+v\n", item)
        }
    }
    return nil
}

func main() {
    if err := run(context.Background()); err != nil {
        fmt.Printf("%+v\n", err)
        os.Exit(2)
    }
}

type Auth struct { }

func (auth Auth) Basic(ctx context.Context, operationName string) (api.Basic, error) {
    return api.Basic{}, errors.New("Why basic authorization?")
}
func (auth Auth) PinterestOAuth2(ctx context.Context, operationName string) (api.PinterestOAuth2, error) {
    return api.PinterestOAuth2{Token: os.Getenv("PINTEREST_TOKEN"), Scopes: []string{}}, nil
}

The very first call to client.AdAccountsList(ctx, api.AdAccountsListParams{}) works correctly, along with the following for ranging over res.GetItems(). However, the call to client.CampaignsList(ctx, params) returns the expected CampaignsListRes interface, but then the second for fails because there's no GetItems() method on CampaignsListRes.

The documentation on Interface responses only has the ...Res interface, so why does client.AdAccountsList(ctx, api.AdAccountsListParams{}) return *AdAccountsListOK?

Here's the generated methods:

func (c *Client) AdAccountsList(ctx context.Context, params AdAccountsListParams) (*AdAccountsListOK, error) {
	res, err := c.sendAdAccountsList(ctx, params)
	return res, err
}

func (c *Client) CampaignsList(ctx context.Context, params CampaignsListParams) (CampaignsListRes, error) {
	res, err := c.sendCampaignsList(ctx, params)
	return res, err
}

Here's my ogen.yml:

generator:
  ignore_not_implemented: ["all"]

Finally, below is the relevant yaml from the Pinterest spec, but I had to fix 5 schema errors (2 excess indentations on minItems; 2 incorrect instances of string type that should be object type; and 1 incorrect usage of maxLength which should be maxItems).

paths:
  /ad_accounts:
    get:
      summary: List ad accounts
      description: |-
        Get a list of the ad_accounts that the "operation user_account" has access to.
        - This includes ad_accounts they own and ad_accounts that are owned by others who have granted them <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>.
      tags:
      - ad_accounts
      operationId: ad_accounts/list
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/query_bookmark'
      - $ref: '#/components/parameters/query_page_size'
      - $ref: '#/components/parameters/query_include_shared_accounts'
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    items:
                      description: Ad accounts
                      items:
                        $ref: '#/components/schemas/AdAccount'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  ...
  /ad_accounts/{ad_account_id}/campaigns:
    get:
      summary: List campaigns
      description: |-
        Get a list of the campaigns in the specified <code>ad_account_id</code>, filtered by the specified options.
        - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts">Business Access</a>: Admin, Analyst, Campaign Manager.
      operationId: campaigns/list
      security:
      - pinterest_oauth2:
        - ads:read
      x-ratelimit-category: ads_read
      x-sandbox: enabled
      parameters:
      - $ref: '#/components/parameters/path_ad_account_id'
      - $ref: '#/components/parameters/query_campaign_ids'
      - $ref: '#/components/parameters/query_entity_statuses'
      - $ref: '#/components/parameters/query_page_size'
      - $ref: '#/components/parameters/query_order'
      - $ref: '#/components/parameters/query_bookmark'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Paginated'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/CampaignResponse'
          description: Success
        '400':
          description: Invalid ad account campaign parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: 400
                message: Invalid ad account campaign parameters.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - campaigns

Any help is appreciated! 🙏

[kszafran]

I believe *AdAccountsListOK is generated for GET /ad_accounts, because the schema lists only a single response other than the default error. In comparison, GET /ad_accounts/{ad_account_id}/campaigns lists multiple responses, which is why ogen generates an interface for the response.

(Aside: Personally, I find this somewhat problematic, since it makes error handling on the client side more difficult. If the schema keeps evolving, documenting an error response in the OpenAPI spec changes how a client needs to handle errors... Checking for err is then no longer enough, and you have to check for the specific error responses, too. This is an issue especially in cases, where you don't care about the response body, just that the request was successful, as can be the case for POST/PUT/PATCH/DELETE requests).