[hpoe]

Just an FYI. This is about Amazon's MWS API, which is Merchant Web Services, used to interact with the Amazon part of Amazon not the AWS side of Amazon.

Also having working on an OSS Ruby library for it, and having to had work with it quite a bit, I can confirm. The MWS APIs leave a lot to be desired of, but they are an absolute gem compared to the Ebay APIs.

My take on the problem is that these APIs were developed in the early to mid 2000's when e-commerce was taking off, so they are architected using the tech and philosophies from back then (XML, SOAP, SOA, etc) however we are no in 2020 and people expect up to date modern interfaces and APIs, and communication protocols; but these API's can't be shut down or risk major breaking changes because so much other stuff is built on top of them.

Really at the core of the day the problem is that so much crap on the Web is considered ephemeral and so many business come and go so quickly that the question of what to do about legacy tech on the web isn't much of an issue because things don't last long enough to be legacy. The exceptions are some of the e-commerce APIs of these big tech companies such as Ebay, and Amazon that managed to thrive, but now are faced with a challenge most people never are of how to migrate legacy web services.

EDIT: Updated appearantly I was not reading closely enough, this is not for the MWS API but the new REST version of their Seller APIs. That being said I'd still be willing to wager a pretty penny they slapped together a REST-to-XML translation layer on top of the MWS APIs and called it a day.

[paradisevoicez]

This is not the MWS API. The MWS Api was indeed written more than 10 years ago but is much better than this new "REST" api.

This is Selling Partner API which was released few months back and is intended to replace MWS.

[brianwawok]

It seems like more or less a wrapper around the MWS api. Many calls are identical.

[breck]

I think you've explained the situation quite well.

I got my career started helping a lot of big companies transition from SOAP/WSDL/XML tech to JSON APIs in the late 2000's (writing API servers and client libraries in PHP, Ruby, Python, and then Node.js) and so thought about these technologies day in and day out for many, many years.

I think we are still missing a dead simpler way to do it all—a very basic Tree/Grid Notation where API requests and responses are equivalent to sending a spreadsheet back and forth (no syntax characters—no quotes, ticks, brackets, parens, etc—just spacing for the encoding). Higher level types would be added onto that, but at the low level it's all about just keeping your data as simple and clean as possible.

Here's a demo I made in 2014 of the idea, which I think is as relevant as ever https://www.youtube.com/watch?v=DV4Nv23bBwQ&t=4s

And another look at it: https://treenotation.org/#apis

[merb]

> Higher level types would be added onto that, but at the low level it's all about just keeping your data as simple and clean as possible.

and at the end we would call it rpc and gave the binary protocol a better name, like protobuf or cap'n'proto?

[breck]

All RPCs would take a tree notation doc as input and return a tree notation doc as output. Tree notation supports no data structures and tree notation supports all data structures. Apis would use only the data structures they need. Binary protocols would be easy to optimize.

[corbin]

Agree with what you have said about the MWS API, but this repo is actually the updated REST based API - which appears to be mostly the same functions as the older API but with less documentation.

[raverbashing]

Don't worry, the docs and APIs/libraries for AWS are just as bad

Boto3 is eye-watering bad. Boto2 was written by someone with some knowledge of Python and usability. Boto3 is just "automatically generated" from their API

It is not good. It is bad. The structure makes no sense. The API can be described as "the minimum that works".

[glaucon]

I'm not here to defend AWS but I'm a bit puzzled by your comment about the Boto3 doco. Here's some sample usage for instance which clearly is something more than "automatically generated" https://boto3.amazonaws.com/v1/documentation/api/latest/guid... .

[typenil]

I believe they meant that the API bindings themselves are autogenerated - which I think is pretty likely given how baffling and un-pythonic some of decisions in boto3 are.

You're right that much of the documentation clearly isn't auto-generated. Of the many Amazon APIs and tools I've worked with, boto3 among the better of them in terms of documentation.

[raverbashing]

Not the docs, the library code is (for the most part) automatically generated

This is actually a good example of how the thing works, you have to use MessageBody as an argument name to send the message. Or use the Entries argument

Those names and that usage style are far from Pythonic

[ArchOversight]

They map to the underlying JSON calls that are made. It's like they took the top-level keys of the JSON and made them kwargs in the Python.

[brianwawok]

EBay added a rest API. They still have the old XML one. They sometimes interact in fun ways!!!

[jlevers]

For some reason the data you send to eBay's REST APIs doesn't always show up in their UI...specifically, if you use their RESTful Inventory API, you can't see _any_ of it from the Selling page! Not sure why...e-commerce APIs seem to be (on average) remarkably bad.

[walshemj]

Even 40 years ago encoding things as free text such as this would have been very bad practice.

And don't get me started on encoding multiple items in a single csv column.