In response to @whysteem's call for input on a new Developers Portal for Steem, I have written this post to summarize a few suggestions.

Most of these ideas came from my initial experience from perusing the API documentation for the first time last week, when I was trying to find direct API methods to get specific data for a Python tool I am making, without using a library, like steem-python.

Categorize or group the methods

It would be helpful to separate the methods some more. Separate those that are considered "stable" compared to the others, for example:

Stable

• QUERIES (for retreiving data)
  • Blockchain: get_account_count, get_active_witnesses, get_block, get_block_header, get_chain_properties, get_dynamic_global_properties
  • Transactions: broadcast_transaction_synchronous, broadcast_transaction_synchronous,
  • Account: get_account_history, get_account_reputations, get_account_votes, get_blog, get_blog_authors
  • Content: get_active_votes, get_content, get_content_replies
  • Market: get_feed_history, get_market_history, get_market_history_buckets, get_order_book
    
    
• ACTIONS (for performing actions)
  • Wallet: transfer, transfer_to_vesting, withdraw_vesting
  • Posting: vote, comment
  • Accont: create_claimed_account, account_update

Beta

• ... put the methods that are in Beta here

Deprecated (historical purposes)

You could also move deprecated methods to their own section, like an archive of sorts. Or exclude them altogether.

Tag mechanism

I also suggest a tag mechanism to allow for dual listing in categories because some methods are useful for multiple categories, e.g. get_reward_fund can go under Market and Blockchain.

More details on parameters

Adding more details to parameter definitions and the range of options will help too. condenser_api.get_reward_fund for example states ["post"] as parameter, which leaves the reader wondering what it's used for and if other options can be used instead.

That's all I have for now. I'll take this opportunity to go through as many methods as I can and test them out. I will share more suggestions as they come.