search

WP-API / docs-v2

Documentation for version 2 of the API
http://v2.wp-api.org
58 stars 71 forks source link

Add a "What Is A REST API?" #45

Open Shelob9 opened 9 years ago

Shelob9 commented 9 years ago

It's unsafe to assume that everyone reading the docs/ using the WordPress REST API knows what a REST API is. Hard to explain what the WordPress REST API is if you can't assume knowledge of REST APIs.

Docs should have a "What Is A REST API?" section that explains what such a thing is, in general and in the context of WordPress. I should write this. If someone else does first, +5 you.

andrewahead4 commented 9 years ago

I quite agree and I think that this maybe the most important element right now to get people to understand why they should use it.

I also think that there are three main beneficiaries of the documentation, producers (adding custom code to the PHP in WP), WP consumers (for either partial elements or complete themes) and for external consumers.

I suspect that the most traction would be gained from the WP consumers as these are the folks out there using WP on a daily basis without being the most knowledgeable about how or why to use the API.

AlbertGuadan commented 9 years ago

The WP REST API, is confusing depending on the user. WP developer= 1front -end, 2back-end, and the 3deep-end. (1. The front end developer will use it to make light integration from a plugin and will typically register at the plugin of origins site and may create an app. (2. The back-end has to install all the necessary requirements for safe data calls and will use a form of authentication (usually a key in the body*) so the data can open access to the data calls/sets with out exposure. GET Sets of data from WP to WP websites: An example of using the API is to find yourself at another WP site and add them to your WP friends list, post on their WP site and the feed shows up at yours. Imagine majority of the world using WP and able to intercommunicate on demand just like some popular social medias do. If I'm logged into my WP i am able to tag a photo in my next post because i friend your WP site. (3. The deep end is to add lets call it a common core inert API safely into core, and must be triggered by using it, (on/off) to be safe across the net.

Luciaisacomputer commented 8 years ago

+1 @Shelob9 what you have so far is pretty good. As @andrewahead4 said, the WHY is a very important consideration for getting more people on board, especially those who are just getting started with any type of API.

Shelob9 commented 8 years ago

@LukePettway I feel bad I didn't get a chance to finish this. Please let me know if you have anything to add in terms of WHY or HOW. I'll try and find time for this next week -- been more over-extended than usual as of late.

Luciaisacomputer commented 8 years ago

@Shelob9 If I get some time today I might start putting something together!

Luciaisacomputer commented 8 years ago

I'm just going to jot some ideas down here and see where we go:

What Does The REST API Allow Me To Do

As stated before, the REST API allows you to easily grab JSON data from your WordPress site which can then be used a number of ways. Imagine being able to dynamically change content on a page easily simply by using a little bit of JavaScript and AJAX to pull in new content. You could even go a step further and decouple the Backend of WordPress and use any technology on the frontend such as Angular or React.

The REST API doesn't just allow you to interact with your data within your WordPress site, it opens up the door for outside apps, services, and other websites to communicate as well. A whole world of possibilities for integrations can now exist. Whether you want to build a custom post editor or a way to integrate your CRM into a WooCommerce site, the sky is the limit.

No longer will WordPress be tied to the technologies it is bundled with, developers will be able to use just about any programming language at their disposal. Now the famous “Five Minute Install” will not only deliver content management, a relational database, and the plugin theme system we expect from WordPress, but it will also include the kind of API expected in modern-day web development tools.

Luciaisacomputer commented 8 years ago

I got some of the ideas for the copy from this post: https://www.elegantthemes.com/blog/editorial/the-wordpress-json-rest-api-wp-api-what-it-is-how-it-works-what-it-means-for-the-future-of-wordpress

Shelob9 commented 8 years ago

@LukePettway feel free to lift from the book I wrote for Torque, first and last chapters especially.

Luciaisacomputer commented 8 years ago

@Shelob9 I have it open right now!