[BUG] Documentation - Incorrect content type

[sherlock270]

If you need help troubleshooting a problem with Selling Partner APIs, please open a support case. Issues are for reporting documentation bugs and enhancements only.

Describe the bug
The incorrect content type is listed under "Consumes" for the patchListingsItem operation under the listings items api

URL of the content on GitHub
https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2020-09-01.md#consumes-3

Description of what the documentation currently says
Documentation says the operation consumes application/json

Description of what the documentation should say
Documentation should state the operation consumes application/json-patch+json per IETF

Additional context
The operation returns an InvalidInput error when using application/json content type. The operation works correctly when using the application/json-patch+json content type

[johnkw]

I'm not seeing any behavior difference between application/json and application/json-patch+json. Is it possible this was fixed to allow both? Or are you just saying the SP-API is not currently in compliance with the RFC's recommendation?

In any case though, both fail with "Invalid path provided in patch at index of 0." because I have no idea what to use for a "path". Bizarrely "path" is undocumented other than a link to a definition of how a path generically is formatted.

See also bug #395 for the more general lack of documentation, including the lack of documentation for "path".

[chapmanjw]

@sherlock270 From a REST purity perspective, I totally agree that the content-type for the PATCH operation should be application/json-patch+json. There are some technical limitations that resulted in using application/json reference. It's possible that application/json-patch+json is being ignored if it happens to be working.

As @johnkw mentioned, we do need better documentation and better links to the documentation we have. For example, the use case guide shows an example of a PATCH request to the Listings API: https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/listings-items-api-use-case-guide/listings-items-api-use-case-guide_2020-09-01.md#step-1-submit-listings-item-patch-request.

The JSON pointer path is formatted as /attributes/ + the name of the attribute being updated. The value follows the structure of the attribute as defined by the Product Type Definitions API.

{
  "productType":"LUGGAGE",
  "patches":[
    {
      "op":"replace",
      "path":"/attributes/item_name",
      "value":[
        {
          "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
          "language_tag": "en_US",
          "marketplace_id": "ATVPDKIKX0DER"
        }
      ]
    },
    {
      "op":"replace",
      "path":"/attributes/purchasable_offer",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "currency": "USD",
          "our_price": [
            {
              "schedule": [
                {
                  "value_with_tax": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "op":"delete",
      "path":"/attributes/item_type_name",
      "value":[
        {
          "marketplace_id": "ATVPDKIKX0DER",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}

[johnkw]

Thanks. It's good to see someone at least looking at these issues. There are so many bugs open right now it sometimes feels hopeless looking at these APIs.

If it's really true that path is just the attribute name, with the string /attributes/ prepended to it, then why not just remove the superfluous /attributes/ from every input, and rename the path field to attribute_name? Then it would be immediately obvious what it actually is, instead of path which is hopelessly vague and confusing.

It seems like this was an attempt to copy RFC 6902, except that it wasn't copied entirely as the original OP points out, and it's not really a good use of RFC 6902, so attempting to use RFC 6902 just makes the API more complicated with no value add.

Also, what is the logical meaning of specifying op as delete but then also specifying a value field? It seems like value cannot possibly be used if the field is being deleted... or at least my imagination fails me for what possible purpose that could have.

[chapmanjw]

@johnkw Great questions. :-)

On the path, /attributes/ is optional. Both /attributes/item_name and /item_name will work. Since the object model of the Listings Items resource puts all of the properties within the attributes property, the path here is meant to represent the path on that resource (so /attributes/ would be more precise).

The JSON Patch modeling used here is a subset of the RFC specification. Not all of the specification is applicable to the use case here, but using this style of modeling was preferable (in my opinion) to making up our own.

The delete case here is interesting. When you look at the JSON Schema from the Product Type Definitions API, you'll note that every attribute is an array and each attribute has selectors (like fulfillment_availability with fulfillment_channel_code). In order to actually delete an instance of an attribute, we need to know which one to delete. There is no particular ordering to the arrays for attributes with multiple instances in the array, so the standard JSON Pointer delete on /attributes/fulfillment_availability/0 doesn't work. In order to delete the right instance, we need to know the selector values (i.e. which fulfillment_channel_code). There were two options we considered (and are potentially still on the table for a future iteration, which your feedback can help with):

1. Keep JSON Pointers, but put the selectors in the value. This is ultimately what we chose for this first iteration. It doesn't change the meaning of the path as defined by the RFC spec, but is not free of being slightly weird.
2. Use JSON Path instead of JSON Pointers. Departing from the RFC spec, we could have used JSON Path where we put the selectors in the path (something like $.attributes.fulfillment_availability[@_.fulfillment_channel_code=BLAH]).

With this in mind, however, our initial release is limited to "whole" attributes (meaning you cannot patch deeper than the top-level attribute and you have to provide the whole attribute). We would like to extend this to "granular" patching where you can patch any field within an attribute. With the selectors, we cannot do that with JSON Pointers. So, we may end up adding support for JSON Path in a future iteration (probably accept both versions for backwards compatibility, since we can easily disambiguate between the two).

Would love your feedback on how we might make this patch operation better in supporting granular patching but also working within the constraints of having to handle selectors.

[johnkw]

Is that only because of marketplace_id? Wait is "marketplace_id": "ATVPDKIKX0DER" part of the definition of what is being updated, but is itself immutable?

[chapmanjw]

marketplace_id is one of the selectors (as these APIs are modeled to support multi-marketplace submissions, which we will enable in the future). Additionally, language_tag is a common selector for textual attributes.

[johnkw]

Honestly this section of the API is incredibly confusing, but thanks for the responses, as it's getting a little more clear what's going here. So SKU is part of the API URL, so, for a given call you can only possibly update 1 SKU ever? But you're allowed to update multiple marketplace_id within the same call? And marketplace_id is an always-required parameter for every single operation?

Why not just make the path parameter just be /SellerID/SKU/marketplace/attribute? Or better yet, don't make it a path at all, but just have every operation have 4 required fields as inputs? (My opinion is that trying to shoehorn this patch RFC into this Amazon situation is just adding to the confusion.)

[Real-dev-byte]

@johnkw @chapmanjw @sherlock270
Using asin name i am using getCatalog to get further details. For patch operation in listings api I am making following assumptions. Please let me know if they are incorrect.
SellerID : used manufacturerCode in vendorDetails in getCatalog response
productType : used productType in productTypes in getCatalog response
SKU : used modelNumber/GTIN/UPC/EAN (whichever present) in getCatalog response

[steven-so]

@chapmanjw @johnkw

Does anyone know what the body supposed to look like when using the patchListingsItem operation to change an image? I'm confused on exactly what I need to provide.

[johnkw]

I haven't tried the scary PATCH stuff, but they finally added GET as per https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2021-08-01.md so you can at least see some of what is available. Strangely it appears the vast majority of fields are not available via the API - it only has the basics. Category specific things like size, color, type are all missing it seems.

[steven-so]

I haven't tried the scary PATCH stuff, but they finally added GET as per https://github.com/amzn/selling-partner-api-docs/blob/main/references/listings-items-api/listingsItems_2021-08-01.md so you can at least see some of what is available. Strangely it appears the vast majority of fields are not available via the API - it only has the basics. Category specific things like size, color, type are all missing it seems.

Yeah it seems like a lot of stuff is missing from the ListingsItemsApi I eventually figured out a way to change images, but I had to use the Feeds API.

[chapmanjw]

For a bit of context here, the Listings APIs are dependent upon migrating product type definitions to support the APIs. Product types themselves are hierarchal with the PRODUCT product type being the root of all other product types. You can refer to the search operation on the Product Type Definitions API to list all of the product types currently migrated: https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/product-type-definitions-api-use-case-guide/definitions-product-types-api-use-case-guide_2020-09-01.md.

For listings with product types that have been migrated, you can read and write all of the attributes associated with that type of item. However, for listings with product types not yet migrated, you are limited to reading and editing attributes on the root PRODUCT product type.

With the Listings APIs, we are iteratively bringing as much functionality to you as quickly as it's available instead of waiting until all product types have migrated worldwide. We are aware that this does not work for all use-cases. As such, XML-based listings feeds with the Feeds API may be a better fit for use-cases that need to cover all available product types worldwide right now.

Mixing and matching XML-feeds and Listings APIs is also supported. For example, you could use the XML product feeds to create and update product facts, but transition to using the Listings APIs for pricing and inventory data.