Improve landing page
kadamwhite opened this issue · comments
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
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 forcontext=view
... and that isn't mentioned anywhere (had to dig into the source to find that out)
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.
mrMark suggests noting that the handbook documents first-party endpoints and the core APIs for creating them; and that plugins may add more information.
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.