Look at the new comments posted since this link hit frontpage. Not helpful, and in fact HARMFUL to open source at large. This is irresponsible.
However, this is the repository to the public documentation of Amazon's API.
This is not the source code to a website somewhere. This is the actual documentation. You ask Amazon for the documentation and they link you to that repository.
This is a company with a revenue of $96.1 billion that relies on sellers to fill its marketplace. You would expect some level of quality.
We had an issue at work with their Seller API. We ended up having to email and call their support daily in order for them to switch an invisible flag on our account. After a month and a half of phone calls, they eventually fixed it.
This is the kind of support you receive from Amazon when you are a seller.
- Seller relations and developer experience
- Marketplace and human resource ethics
- ?
That said, I wrote documentation professionally for a few years in my career, and recently re-worked much of CRACO's documentation, and there is very little love for docs.
Docs are hard to do well and completely and if the API is as bad as described, you can only shine up a turd so much in explaining how something works.
Sometimes writing documentation is the only way someone realizes that the software is broken or not actually useful as implemented.
In most situations, a product manager is looking out for this in advance, but when the product is purely an API you have less product-type people who can provide useful management.
Obviously it is not a revenue problem at Amazon. Perhaps this is anger at Amazon's astonishing success redirected to areas of Amazon that have failed to realize the resources to make quality products.
// the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad.
// a completed batch looks like this:
// <Batch>batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 </Batch>
// and an incomplete batch like:
// <Batch>batchid=363778361 status=In Progress </Batch>
// so we'll just parse each item as a regex. Thanks Amazon.
There's also 4 (4!!!) different ways of returning errors in the MWS Feed APIs when used from Java. Given the number of entities, and the fact that they're combinatorial I had to do some of the craziest Scala code I've ever written because duplication was just too bad to handle for how critical that code was. To do it in a bulletproof way, that error handling for MWS feeds inherently has 2^4 control flows * N entities = 16N code paths at like 100-200 lines a piece if you didn't use some higher order abstractions.
<Batch batchstate="batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17" />
:)
<xml> <office-proprietary-binary-blob> wky4b5tlwybkjbb2... </office-proprietary-binary-blob> </xml>
And it seems after 2007 they switched to an ECMA standard.
Philosophically speaking, is this any different than 'syntactic salt' for a 'Batch' JSON object? ;)
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.
(Shameless plug: I wrote detailed walkthroughs of how to get access to[0] and build a basic application with[1] the Selling Partner API).
[0] https://jesseevers.com/selling-partner-api-access/ [1] https://jesseevers.com/spapi-first-application/
Their entire experience w/ Amazon starts at the website and ends with the brown box with the smile on it.
I am not defending anyone only pointing out that maybe we shouldn't have entities so big that dissociation of mid to high level management decision's to reality is so easy. Where guilt and responsibility is pushed down the ladder on daily basis.
What are you doing to do? Deal with it or decide to not sell your products?
Before you hate on CORBA I submit that my masters thesis was based on CORBA for distributed processing and that, "horror of horrors" it had solutions for many of today's issues.. albeit implemented with tooling that was lacking. Anyone for a game of what vendors RPC implementation this is based on packet dumps?
I forget the specifics of how the example code worked but it acted as both a sender and receiver of DDE messages and did so by executing itself. I remember spending a good 30 minutes trying to work out how the example worked before giving up and doing the classic “let’s just run it and see what happens” approach.
The example code from Microsoft turned out to be a fork bomb and it quickly crashed my machine.
It took me a long time to trust Microsoft documentation again after that incident.
The Pull Request:
https://github.com/amzn/selling-partner-api-docs/pull/209
The Deployed Docs:
https://docs.contour.so/amzn/selling-partner-api-docs
Lots of bugs still to fix but hopefully it's helpful to anyone. Super open to any feedback!
---- Edit: To make it clear, the docs are built on a web app I built while on break from school. Sorry if that wasn't clear before!
Sure, it makes navigating this version of the docs slightly easier, but this doesn't seem to be a good-faith attempt at actually improving the documentation so much as promoting your service.
But yeah, I could definitely see how it would come across this way, and I'll revert the links back to the PR! Hope that helps.
Also, I do not think contour.so addresses any of the real concerns about the documentation.
In which case either Amazon is or isn't important to them. If it is, they can just tell the person to get over it and do their job. If it isn't then they aren't an important customer for Amazon either.
In neither case is there any incentive for Amazon to improve.
Such is life with a lot of enterprise software in my experience.
One step we could take is in hiring. When interviewing developers, let's ask them to write documentation, not just code.
The previous/legacy MWS API was actually way worse. Though the documentation may have been a bit more coherent.
(So why should the bother fixing it?)
It was clear for a long time that developers were not considered customers, or if they were, they were far less important ones.
This is Selling Partner API which was released few months back and is intended to replace MWS.
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
and at the end we would call it rpc and gave the binary protocol a better name, like protobuf or cap'n'proto?
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".
And don't get me started on encoding multiple items in a single csv column.
Really underrated.
Getting out of sync happens very quickly if docs aren't generated from source and aren't an integral part of the release process.
Every change in API or behaviour should be automatically blocked by CI tooling in release builds if its documentation is missing or outdated.
But alas, even in 2020 technical documentation is still just an afterthought for most companies - even big ones.
1) Make code changes to a specific microservice. (note: The Open API Spec also lives in code.)
2) CI/CD pipelines get triggered.
3) New microservice is built.
4) Call every REST endpoint defined in the microservice's Open API Spec and validate it using the example requests/responses.
5) If successful, regenerate the API documentation from the Open API Spec.
This ensures that our documentation and services will stay inline with each other.
[0] https://doc.rust-lang.org/rustdoc/documentation-tests.html
OpenCV can’t be assed to link out to source, and also won’t even bother telling you what the function signatures are, what the names of all the methods are, or anything else useful.
and the conditions have only been improving, and with more robots, the number of warehouse workers will only keep getting less. drivers on the other hand is a different story..
But yeah, Python made it usable :)
It's somewhat specific to golang but so far it has been relatively good for us.
The spec is directly next to the code as code comments, so it has far more chances to get updated when changes are made compared to an external documentation.
Also, the payloads and responses are directly derived from the Golang structs, so, at least on that aspect, changes in the code are automatically reflected in the spec (apart for description and examples).
We also put the interactive documentation directly in our API under /doc. It is a useful tool for developers when implementing a new url/handler or modifying an existing one. It also creates incentives to keep the documentation matching.
Overall, we had very few mismatches between the spec and the actual implementation overall, despite not having deeply tested it (be it manually or automatically). Apart from one or two mismatches that were fixed quickly, I was able to take the spec, generate client libraries from it (swagger-codegen), and use them for quite extensive demos without issues.
We are still early in the project (not in production yet), and there are definitely some aspects we need to improve (integration/automated tests to be sure doc and code are 100% matching) or to completely figure out (ex: how to handle several versions of the same API). But overall, using swaggo/swag has been a pleasant experience.
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.
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