Improve landing page

[kadamwhite]

Proposals from docs-focused API team meeting on Jan 2, 2020:

• Move Key Concepts into its own page
• Add some API basics:
  • The API exposes information about your site, but also provides a toolkit for creating your own endpoints; it's a REST API and a set of PHP api's for building a REST API, basically
  • Security misconceptions: we expose public data, accessible from anywhere (link to FAQ for lockdown maybe) and require authentication for sensitive data
  • Explain meta must be explicitly registered (link to that page in "extending")
• Demote technical content on the page and open with the usage rationale

[kadamwhite]

From pbiron:

I went thru the whole handbook yesterday/this morning and didn't see anything that explicitly said context=edit requires authentication, others don't. Plus, as I discovered yesterday, /wp/users/role=xxx and /wp-users/who=authors also require authentication even for context=view... and that isn't mentioned anywhere (had to dig into the source to find that out)

[kadamwhite]

From dshanske:

You find out all these endpoints are available and you see what they do and it seems overwhelming

How to explain the scope of what's available without it being overwhelming? 🤔

[we should] bring more of the "why" up to the top

Using the WordPress REST API you can create a plugin to provide an entirely new admin experiences for WordPress, build a brand new interactive front-end experience, or bring your WordPress content into completely separate applications.

This should be the first sentence, it's on the page already

You've already lost a reader by having the technical first

We should therefore demote the technical content of the page, and keep the absolute intro segment more usage-oriented.

[kadamwhite]

mrMark suggests noting that the handbook documents first-party endpoints and the core APIs for creating them; and that plugins may add more information.

[kadamwhite]

We should note that

• The API is a core part of WP
• It must be enabled for WP to function
• It exposes already-public information
  and then link to a more in-depth privacy article.