OpenAPI V2 schema definition for `/products` response is broken

API
, ,
1

There seems to be some erroneous double nesting defined in the OpenAPI v2 bundle for `/products` GET endpoint response - notice the nested data → data arrays due to the extra GetProductResponse object which shouldn’t exist there at all:

schema:                                                                                
  title: GetProductsResponse                                                           
  type: object                                                                         
  properties:                                                                          
    success:                                                                           
      type: boolean                                                                    
    data:                                                                              
      type: array                                                                      
      items:                                                                           
        title: GetProductResponse                                                      
        type: object                                                                   
        properties:                                                                    
          success:                                                                     
            type: boolean                                                              
          data:                                                                        
            - title: BaseProduct
              allOf:
                - type: Object
                  properties:
                  # ... properties for `Product`

Based on currently provided schema, OpenAPI-based tooling expects data with following structure:

{'success': true, data: [
    {'success': true, 'data': [{ product_object }]},
    {'success': true, 'data': [{ product_object }]},
    ...
],
...
}

Also, the BaseProduct is missing some properties (add_time, update_time, description, category).

Here’s one way to fix the bundle to correspond to real data from endpoint:

yq -i '
  .paths."/products".get.responses."200".content."application/json".schema.properties.data as $d |
  .paths."/products".get.responses."200".content."application/json".schema.properties.data.items = (
    $d.items.properties.data.allOf[0] |
    .allOf[0].properties += {
      "add_time": {"type": "string"},
      "update_time": {"type": "string"},
      "description": {"type": "string"},
      "category": {"type": "string"}
    }
)
' openapi-v2.yaml

Few more issues:

  • There’s no support to query changed products by updated_since :frowning:
  • The .prices property (this is actually dropped by my custom patch) is lacking object structure.
  • Linking products to deals? (Properly syncing these many2many objects)
2

Hey! Thanks for the reports. We’ve fixed the schema inaccuracies you ran into:

  • GET /api/v2/products response was double-nested — now correctly describes data as an array of products
  • Missing fields added: add_time, update_time, description, category
  • prices items now have proper field definitions instead of an empty object
  • updated_since query parameter was actually already supported in the GET /api/v2/products endpoint, it just had not been documented properly. Added now

On the question about linking products to deals — this is fully supported. You can list, add, update and delete deal products using the GET/POST/PATCH/DELETE /api/v2/deals/{id}/products endpoints. Let us know if this is not what you had in mind!

1 Like
3

On the question about linking products to deals — this is fully supported. You can list, add, update and delete deal products using the GET/POST/PATCH/DELETE /api/v2/deals/{id}/products endpoints. Let us know if this is not what you had in mind!

My complaint was more about syncing the DealProducts entities themselves. Fortunately changing the details for attached products also updates Deals’ update_time field.

It’s just the issue that one has to keep track of the Deal.DealProducts sync time in separate entity. We do it like this: Deal has update_time and products_update_time. First one gets updated when Deals are synced and in the second pass we gather all the deal objects where these two fields are different. And then use /api/v2/deals/products with the deal_ids. (Also, that API was also broken until this week).