Why is there essentially no documentation on how to use the JSON endpoint?
I've spent the past week and a half trying to implement a C# service that accesses user email accounts using OAuth to pull receipts from the account so that we do not have to store user email accounts. I was able to use OAuth to access Gmail accounts quite easily because they allow IMAP access so I can use pretty much any IMAP library to handle all of the authorization and calls. Took a day, maybe two to make a finished product.
Now onto Yahoo, I realized that I could not access the account using IMAP (why? that would make life so much easier) so I would have to use the API. That's ok, the Yahoo Mail API appears to be well documented! Looks like they recommend using SOAP as all of the example requests and responses are SOAP objects. Oh no, they deprecated the SOAP endpoint a year ago! Good thing I read the one tiny line in the "Getting Started" page that mentions that the SOAP endpoint was deprecated. Seeing as to how EVERY SINGLE EXAMPLE IS IN SOAP I would have had no idea. Maybe this forum would help, nope the only help as to how to use the JSON endpoint is one post with a link to some guys GitHub (https://github.com/ramiyer/YahooMailApiSample) with a Java App that runs requests.
In order to figure out how to use this API I had to debug the Java App, using trial and error to generate valid requests. The descriptions of the request parameters are actually quite vague and often misrepresent what can be used for a parameter, FYI XML (SOAP) does not always translate directly into JSON, in fact there are several cases that they do not. I then had to step through the code so I can see the values of certain variables at different states and to access the responses to figure out how to process them in my C# service. This took about a week... And also very there is very little documenting how to use OAuth to authorize the requests. That is a whole other task. If you're going to make the process of using this API difficult, you should make libraries for some of the major libraries to help people use your service.
Sorry for this rant that pretty much lacked any questions. I think it would really help your users out if you were to write out documentation on the JSON endpoint with example requests and responses, as well as some help with using OAuth in the requests. It took me way longer than it should have just to get a working prototype together. I expected much better from you Yahoo...
I do understand and agree to most of the points. Few things
We recommend JsonRPC
We are currently only supporting OAuth for Web Apis and it should work pretty much how any RPC or Rest entry point should work and the sample app is just what it literally means "a sample". It is not an SDK or a starting point to write an app on Ymail APIs. The only thing it helps is it tells how your json should look like when you send it to the server which is in the README
If you have any API related question please post in the forum and someone should respond to it.