More documentation and tutorials, specifically for new users

vthornheart-bng commented 6 years ago

Right now, we have fleshed out some of the "detail" documentation better than we did in D1: but we're still missing the core introductory experience for people first learning how to use the API.

There's no pointer for "how you get started", which I think would at least include:

How to initially register your application, get an API key, and set yourself up for OAuth (at least in the latter case, we do have a tutorial we can link to)
How to find someone's Membership ID for example, and use it to fish out the important "core" Destiny information needed to make calls to other parts of the API. Also the different "points of entry" you might use: for instance, some devs might want to start with your Bungie.Net information, while others might just care about your information for a specific Platform. It's a different experience in those two paths, so it would be good to talk about what you have to do for both of those and why you would start with one over the other.
What it means for an account to have multiple Membership IDs, and what it means to have membership IDs of multiple types.
The distinction between and meaning of a Membership ID, Character ID, Item ID, and "Entity Hashes".
The relationship between dynamic data pulled from the API, and static data pulled from the Manifest Databases.
How to set yourself up to extract the Manifest databases
How to set yourself up to automatically or periodically check for new Manifest database updates
Examples for the above in at least one code language, at least just for this "how to get started" tutorial if nothing else

I would also like to follow the suggestion in #303 and provide helper visuals for parts of the API that are confusing:

Diagrams for the tutorial information above
Diagrams or in-game screenshots for concepts in the API that are confusing, particularly places where I attempt to explain it with a wall of text (like Vendors, or the ever-increasingly-complicated Socket/Plug system).

Does anyone else have suggestions for places in the API that they wish had more fleshed out documentation?

vpzed commented 6 years ago

I can provide some info on some of these topics. I haven't tackled Oauth yet, but other items I have some samples. I could try putting together some info and putting it on my Wiki for your review, or would you prefer some other method?

vthornheart-bng commented 6 years ago

If you're willing to do that, that would be wonderful! Thank you!

vpzed commented 6 years ago

Unfortunately I can't personally help with what at least in the Discord seems to be the most common question - getting Oauth working for various app types (client-only website, website with front-end and back-end, mobile application (Android/iOS), etc) - with actual examples. Even the long standing BungiePlatformDev Wiki doesn't have code examples for Oauth 2.0.

The Wiki here has some useful information but even with that I see a lot of questions in the community about it every week.

ckhicks commented 6 years ago

I'm definitely interested in helping with these areas, specifically OAuth for browser/JS apps, as that seems to be a hard start for many people. This is a really good list.

vthornheart-bng commented 6 years ago

Awesome, and thank you both! Indeed, if there is any one place that would be most benefited and most feasible to do for people who aren't working at Bungie itself to help with the API, making community-driven documentation is certainly it. We can't really provide things at this time like access to our internal infrastructure for early testing, or access to the proprietary codebase... but documentation is something that would help a ton of people, and that actually can be done without either of those things.

I'll have to make a list of who I owe beer to. ;)

For OAuth, I wonder if making this more visible would help: https://github.com/Bungie-net/api/wiki or if that's insufficient for people's OAuth questions - if there are areas where people are getting confused with OAuth, I'd definitely love to add more documentation to help with that too.

vpzed commented 6 years ago

I've pointed people to that information and it hasn't helped them, so I'd say it is not sufficient for new people. It contains enough information for people who are familiar with Oauth 2.0 and need to know how to use it for the Bungie API, but not enough information for those not experienced with Oauth 2.0 to comprehend how to get started top to bottom. This area especially ties in tightly with the Bungie Application setup screen and other application factors (like client-only website, native app, etc).

vthornheart-bng commented 6 years ago

Ah, that makes a lot of sense. Hmm... yes, that would be good, perhaps either a link to or our own "Bungie API specific" conversation about OAuth itself and how it works.

xlxCLUxlx commented 6 years ago

Here is a link to my Wiki that I started in case anyone needs a tutorial on clan banners. I plan on adding more stuff (i.e. things mentioned above as time permits with work schedule). Most of my stuff is in C#. I also give a working code example for instance in the clan banners.

https://github.com/xlxCLUxlx/Destiny2API/wiki

hskrasek commented 6 years ago

Not sure if it'd help or be useful, but I could try and document all the tinkering I've done with the Milestone API's to create my Slack weekly milestone bot.

vpzed commented 6 years ago

I have an open invitation for documentation on the unofficial Discord server for articles. I have started a small Wiki at https://github.com/vpzed/Destiny2-API-Info/wiki that has the posts so far.

For example I have several articles on the Manifest including some good detail on using JSON queries to aid in manifest data retrieval.

There is also a pretty good list of open source projects I have found related to the Destiny API.

If anyone would like to add to the article list just let me know. One way this has worked is an author has sent me a link to a text Gist in markdown format which I then copy over to the wiki and attribute the article to them.

Or in some cases like with @xlxCLUxlx article I chose a different route to get clan banners, but got inspiration from his article so I linked to his article in my post. So people who want to know the better way to do it (xlxCLUxlx's way is the real deal) then they have the reference.

ckhicks commented 6 years ago

All righty, just so this trail doesn't grow cold, I whipped up a vanilla JS + PHP example for going between auth codes and refresh tokens for confidential apps.

Since it assumes that it's okay to expose credentials in the browser - which is definitely not a good idea - you would want to change it before using this in production. But it's a good thought-starter for those confused by the overall flow: https://gist.github.com/ckhicks/76c229dfaf94236cba72b72467f41654

More later!

vpzed commented 6 years ago

I recently added a new article to my Wiki on Leviathan raid encounter order. https://github.com/vpzed/Destiny2-API-Info/wiki/Leviathan-Raid-Encounter-Rotation-Info

This is another community article that shows community members working together to answer questions that commonly come-up in chat.

vthornheart-bng commented 6 years ago

Awesome, love it!

nine13tech commented 6 years ago

I am happy to write up how to do OAuth from a Python perspective. We have a working Bungie OAuth 2.0 suite with my inclusions to the Python-Social-Auth package. I can finish it out with how to pull the username and the differences between the bungieNet membershipId and the destiny membershipId and what is really tied to what. (also - that is really confusing to a lot of people... I had to "rename" the bungieNet membershipId to uid for other devs so it made sense and fits with the Django model)

see here: https://python-social-auth.readthedocs.io/en/latest/backends/bungie.html

nine13tech commented 6 years ago

Maybe we need a BungieNet API Wiki with pull requests!

vpzed commented 6 years ago

I looked at it awhile back but got side tracked and didn’t get back to it. Good idea.

On Wed, Dec 20, 2017 at 8:36 PM nine13tech notifications@github.com wrote:

Maybe we need a BungieNet API Wiki with pull requests!

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/Bungie-net/api/issues/341#issuecomment-353242012, or mute the thread https://github.com/notifications/unsubscribe-auth/AcvepLmDSnPzXGF4pvCj0rm98HKcyLrrks5tCcQ3gaJpZM4RCSlo .

ckhicks commented 6 years ago

That's a really good idea.

vpzed commented 6 years ago

OK. I've updated my Wiki with the ability to accept pull requests and added the special repo link to the Footer of the Wiki. Basically you can'd do pull requests for normal Github wikis, BUT there is a way to work around that and that is what I've setup. So you fork and do the pull request on the "special repository" and when I merge the pull request it will update the wiki in the "normal repository".

The special repository that people can fork and issue pull requests to is:

https://github.com/vpzed/Destiny2-API-Info-wiki

Once merged it will update the original wiki Pretty cool.

vpzed commented 6 years ago

@vthornheart-bng I updated my Wiki with three new beginner oriented articles. Feedback is appreciated. Let me know if this is the kind of thing you are wanting to see, what needs changed, etc.

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-1-Setup

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-2-Account-Concepts

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-3-Manifest

Edit: BTW, with these articles I'm trying to introduce concepts before getting into code samples.

PS: Happy holidays!

ckhicks commented 6 years ago

Good call using Postman for the introduction - great stuff so far!

vpzed commented 6 years ago

Two more articles are online.

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-4-Item-Concepts

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-5-Item-Examples

With these five articles I think I have covered a lot of the initial topics requested at the concept level (with specific API examples). Please let me know what you think about the content so far, what I missed, etc. I want to solidify the concept entries before moving too far into code examples because I want the code examples to build off of the concept articles.

vthornheart-bng commented 6 years ago

Awesome, looks great! Thank you for making those, it is deeply appreciated!

vpzed commented 6 years ago

OK, if those are OK then I'll continue in that vein. I'll re-read the original post and see if I find things that I missed. If not then I'll look at adding some code samples.

xlxCLUxlx commented 6 years ago

Happy New Year!

I am finally starting to get back into swing of things and have started some additional detailed documentation to help users out.

My initial item is around the Bungie.net Application Portal and goes into detail about each section in the portal to help a developer decided what options they should be selecting or filling in. This document can be found here:

Bungie.net Application Portal

I have also written an OAuth provider in C# (based on Microsoft Project Katana and OWIN) as well as a sample web site (ASP.net MVC 5) that developers can use to step through and debug the OAuth workflow and see how it can be consumed. I need to do a self code review (make sure XML comments, etc. are in place and get the code on GitHub) as well as write documentation on the OAuth for a wiki. I will update this comment once I am able to get that done.

Cheers!

Tetron-bng commented 6 years ago

Nice. This looks great! Thanks for putting the effort into helping the community understand our APIs.

vpzed commented 6 years ago

@xlxCLUxlx That is awesome.

In addition to linking to your Clan Banner article in my banner article, I updated my Setup article to link to your application portal article. I also created a new Other Resources page on my wiki and linked to your wiki as a resource so you are linked in each area where our content overlaps. :)

https://github.com/vpzed/Destiny2-API-Info/wiki/API-Introduction-Part-X-Other-Resources

xlxCLUxlx commented 6 years ago

Not sure if this is helpful or not but I created a sudo UML Object Model Diagram for each API endpoint as well as each Destiny.Definitions. object and put them into a PDF that people can navigate. So for a particular endpoint for example it will show you in a UML format all objects you would need to work with to get at different information. Each object's header is in turn is linked back to the corresponding https://bungie-net.github.io/multi/index.html documentation. Each member in an object is either linked to a definition where it will take you to that definitions page (if a mapped definition) or to the definition itself within the current page. The documentation is derived from the openapi-2.json file and makes use of the x- extensions except for x-dictionary-key since that appears only be in the version 3.0 document which I need to switch over to and an oversight on my part. It ended up being a 140 pages so their is also a table of contents that is linked to each page along with a legend. Hopefully it provides a high level view with the ability to drill into the official documentation based on the links.

Bungie.Net API Object Model

Hope it can help someone!

Regards,

xlxCLUxlx

vthornheart-bng commented 6 years ago

Very nice, I dig it! Awesome stuff!

seriussoft commented 5 years ago

Is the any more movement with this initiative?

I'm working on a closed-src mobile app (c# x-platform for UWP/Android/iOS via Xamarin) and website project (Srry, gotta feed my kid)...

And I planned to build an open-src desktop GUI app (winforms and/or wpf/uwp/xaml) for testing my wrapper API for usability criteria as well as have everything in said API wrapper be open-src including a how-to documentation because I love sharing with and educating others.

Saw this quasi-official group effort, & thought this would be a wonderful place to share my efforts and results.

Is this initiative ongoing?

floatingatoll commented 5 years ago

Be aware of the following Bungie.net EULA clause, if you aren’t already:

You must not sell or earn any revenue or other compensation from Your Content, including any advertising revenue or subscription revenue.

On Jul 16, 2019, at 22:50, Nate VanBuskirk notifications@github.com wrote:

Is the any more movement with this initiative?

I'm working on a closed-src mobile app (c# x-platform for UWP/Android/iOS via Xamarin) and website project (Srry, gotta feed my kid)...

And I planned to build an open-src desktop GUI app (winforms and/or wpf/uwp/xaml) for testing my wrapper API for usability criteria as well as have everything in said API wrapper be open-src including a how-to documentation because I love sharing with and educating others.

Saw this quasi-official group effort, & thought this would be a wonderful place to share my efforts and results.

Is this initiative ongoing?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

seriussoft commented 5 years ago

Thanks, @floatingatoll , for the reminder. Sadly that means that those who wish to enjoy the fruits of my labor will have to use 2 separate apps instead of just 1, but this is the spice 🌶 of life. 😄

While I'll have to make the extra conscious effort to keep my for-pay mobile projects separate from the API backed project(s) during planning and development, ultimately it doesn't affect my closed/open source decision because my reasoning was less about capitalism & more about legality & time expenditure.

Basically, I have some proprietary tools and API's I've built over time that I use for some of my contract/freelance work to speed up production and minimize costs that I am not willing in some cases and in most cases am flat out unable to throw into the public domain (I own IP rights to all of it, but there are special rules that prevent some from being used in certain license models because they were not already fully in the public domain at the time I used them in work for my clients).

But i appreciate the reminder, not just for me, but also for any that might read this convo.

Thanks, Nate

vthornheart-bng commented 5 years ago

Aye, unfortunately we've had no time to work on improving documentation or creating tutorials - all that work got postponed for things like Cross Save, Shadowkeep, and work related to the move away from Activision and bootstrapping additional publishing-related features into the website.

I'm still hoping to loop back to it if we get the resources to do so, but sadly the documentation is low on the totem pole with all these time-sensitive deadlines and the minimal staff we have for working on the API. Which is a bummer, and I would like to see that change if we could get the resources dedicated to it.

seriussoft commented 5 years ago

I appreciate the response and candidness, @vthornheart-bng . As I'm able to get farther along, I'll try to make the conscious effort to add notes into something consumable (markdown, html, or similar) so that I can better share that with people from both perspectives brought up above:

Those new to OAuth specifically and/or general web API consumption needing more information to get started.
Those familiar with OAth, just needing the quick cheatsheet to get going.

My Experience

I'm more API focused as a dev, so I hope that I can bring something useful to the table. Ignoring my initial amateur dev exp, I got started professionally as a dev creating wrappers for SQL in Java and C# both while teaching people C# with those wrappers (while allowing me to focus on teaching them the fundamentals), as well as building wrapper GUI control classes that could be consumed with minimal understanding of what made the metaphorical car drive. So I've spent most of my dev career working with, building, and consuming APIs that let people learn to drive before they understand the physics and chemistry that makes engines, anti-lock breaks, & automatic gear-shifting possible.

So, should I just make the occasional entry here when I make headway with certain sections along with links to the documentation and example code I accumulate? Or is there a better place or preferred method?

I know that getting support for things developers want in a large project with multiple priorities often relies greatly on those devs with the time and resources to put forth the effort and share their work in hopes that it picks up steam and gets the attention of decision makers but the understanding it may not receive any limelight. I've got the time and the capacity, and my time is spent either writing code or grinding in Destiny while testing my code as I heal in my recovery chair.

vthornheart-bng commented 5 years ago

Yeah, if you're got the time and the motivation to write up community guides, that sounds good to me! We could put them in the wiki alongside the (sparse) existing guides that we have. I'll buy you a beer if you ever find yourself out here!

vpzed commented 5 years ago

I still have my Wiki repository at https://github.com/vpzed/Destiny2-API-Info which can be updated via PR to get content on https://github.com/vpzed/Destiny2-API-Info/wiki I covered the basics there to get new folks started but there is a lot more that could be added.

vthornheart-bng commented 5 years ago

Oh, yes! That is a very good point! Indeed @seriussoft that is a good place to contribute!

seriussoft commented 5 years ago

Awesome sauce. I appreciate the links, the headstart, and the chance to add to what y'all have already put together. (I know, I'm that weird developer that actually likes documentation, both the act of making & consuming it).

I'll try my best to rely on programming language agnostic examples where possible while relying on the ability to see how to do things from the perspective of reader's choice of lingo, otherwise, (thinking C#, VB.NET, PHP, and MAYBE other popular free languages picked from Ruby/Golang/Java/C++/Python/JS as time allows) and not too different from how Microsoft does their documentation.

My focus will be C# because I'm building my mobile, web, and x-platform apps via xamarin/asp.net with C# (VB.NET examples will come free because they both compile to nearly identical IL instructions in most situations and converting code is practically free), so the other language examples will come later.

I'll leave openings for those with time to also add in with appropriate language examples, but I think that the above list of mainstream programming languages SHOULD cover MOST bases such that devs with different tastes likely will have enough experience to apply to their language of choice.

Bungie-net / api

More documentation and tutorials, specifically for new users #341