Improve landing page - Githubissues

WP-API / docs

The content for developer.wordpress.org/rest-api

https://developer.wordpress.org/rest-api

110 stars 621 forks source link

Improve landing page #76

Open kadamwhite opened 4 years ago

kadamwhite commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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? :thinking:

[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 commented 4 years ago

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 commented 4 years ago

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.