Giters

WP-API / docs

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

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

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Improve landing page

kadamwhite opened this issue · comments

commented

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
commented

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)

commented

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.

commented

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

commented

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.