[Steemit For Developers] It's Time for Delightful, Organized, and Example Rich API Documentation!
Image by @cass
The importance of a well documented API is enormous and ultimately can make it a pleasure to develop or integrate with. As new developers or 3rd party services start looking to integrate with steemit, there should be a simple developer docs accessible directly on our site.
Our API documentation should be easily found, delightful, organized, and have lots of examples.
We have a great deal of eager developer and 3rd party services who are accustomed to robust documentation which can be generally accessed directly on the main destination
Not by scouring or filtering a bunch of posts to find the solutions. It's time we up our API documentation!
Steemit Developer Collective Docs have arrived!
Logo design by @cass
Steemit Developer Docs
The new steemit developer docs, now live, can be viewed at: https://steemit.github.io/steemit-docs/Ideally we'll add this directly in our menu for new developers. Also having a direct link from our domain would be ideal http://developers.steemit.com or http://steemit.com/docs for examples(Github pages supports custom domains)
The open source repository can be viewed at: https://github.com/steemit/steemit-docs
Coverage of existing API functionality on the developer docs is currently limited but growing! *Currently, only steem developers can commit. If your a developer and would like to help contribute please contact me!
Preview
To get started, I've modified and themed slate's default UI/Styling to match the elegant and simplicity we currently have on steemit.com. The hope is the developer collective will become our official API documentation for developers and 3rd party services easily accessible in our menu. Aesthetically, it needs balance to fit well with our main site and carry over.
Together, Lets Create Delightful Documentation
Examples - For any endpoints and RPC commands it's good we give examples of expected output along with optional and require parameters. Nothing is more upsetting tapping into a 3rd party API and having to guess what optoins the payload is expecting.
Formatting - Easy to ingest, locate commands and data points. The steemit developer docs already have a search engine integrated which makes it pleasant to find resources.
Tookit/Libraries/Wrappers - We already have an incredible amount of libraries and wrappers, @fabien has amazing progress on SteemJS, @xeroc has built the great python command line tool piston, just to name a few. Let's categorize all our current and future libraries, wrappers, and components into a robust toolbox center for everyone!
Quick Hightlights
- We're utilizing the Slate API Documentation framework. Slate is a light, elegant and mobile friendly interface for building robust API documentation. It's utilized to build API documentation by companies including Mozilla, Dwolla, Clearbit, and NASA. We're in good company!
Slate is just Markdown. Developers can help contribute using a simple and light syntax we're all familiar with.
Hosting is extremely trivial and no added cost for us :) Were all hosted and already live on Github Pages!
Recap
With the Developer Collective Docs in place, we are primed to grow and collectively curate delightful and comprehensive API documentation for anyone looking to develop on steem. Let's aim to set the highest standard we can. It's exciting to take one step forward today for that vision!
Well done! Are there any consolation prizes for us devs who slagged through all those posts prior to organized docs? Hahah. Great work here. Thank you.
Haha. Would be nice.. I was one of those devs too :) Hoping to make it easier for the next batch.
Sounds like a fantastic idea to me. Part of me will miss digging through source to find out what parameters to use... But not much. Not much at all. :)
Thanks for your hard work and its quality! Namaste :)
https://steemit.com/steem/@klye/an-introduction-to-steemd-api-calls-functions-and-usage
Here is a backbone of some documentation if anyone wants to copypasta it for steemd API calls.
Currently working on cli_wallet docs and waiting for email replies from coinpayments . :)
Great recap let's get it all in! Some of the coverage is already there I added a few days ago. @klye did you want to help contribute to the steemit docs? Now we can get coinpayments a link to official documentation, something they probably wanted. I'm working on getting a good URL for us (steemit.com/docs) :)
https://steemit.github.io/steemit-docs/
Yeah I'll give you a hand.
Was building http://steem.global up to house API reference info but this seems a lot nicer layout to be fair.
I added this: https://steemit.com/steemapidocs/@cryptomental/steem-online-uml-graph-my-2-cents-added-to-steemit-developer-docs
might be also useful...
good work dudes 8]
@faddat you will sleep better mate now Ahaha
I have no clue if this particular idea will successfully fill the void of documentation. Let's hope so though. Promoted for PSA value.
Thank you so so much. You will save new developers for the platform a huge wasted time. After 2 months working for steemit i'm still struggling to search for APIs. It's a developer life saver post. Many thanks.
great. i need it
yeahh!!!!