Is there a JavaScript API? How to access public and private data in JS?

TL;DR

There is no JavaScript API in the WordPress core and no one is planned, but actually, there is no need of it.

Backend

First of all let’s say that, regarding the backend, some useful information can be fetched from already present JavaScript global variables (WordPress loves all global flavors).

E.g.

  • ajaxurl for the admin-ajax.php url to be used in ajax calls
  • pagenow for current admin page slug, e.g. ‘dashboard’
  • adminpage for current admin page file, e.g. ‘index-php’ (dots are replaced with hiphens)
  • typenow for current post type while in edit.php, post.php or post-new.php
  • userSettings can be used to get information oc current logged user

Those information gives you some “context” of the application state while you are in the backend.

For other things mentioned in the question, you don’t need any “API”, because super-simple jQuery functions can do the trick. For e.g. to know if the admin menu is closed you can check for the “folded” class in body:

if ( $(body).hasClass('folded') ) {
  alert( 'Admin left menu is closed!' );
} else {
  alert( 'Admin left menu is open!' );
}

Documentation Lack

For things like the previous snippets it isn’t worth to create functions. WP already has too many functions in PHP. I really hope that additional functions like those will not be added to core.

What JavaScript in WordPress really needs is more documentation for existing features: none of the things I have written above are documented in any official docs like the Codex or in source files.

Frontend?

Until here I’ve only talked about the backend.

This is because pretty much all the things that happen on the frontend are related to the theme currently in use. Let’s imagine there is a JavaScript file provided by WordPress containing functions to get information about the current application state; if a theme doesn’t enqueue that JS file, those functions are not available and to force a theme to enqueue such a script would be absolutely wrong.

No need of (another) API

However, in WordPress, every information you can get via PHP can be easily used in JavaScript too and without any AJAX request. That function that makes this possible is wp_localize_script().

Let’s assume you want to get the current user and user data like its user-role in your JavaScript and you also want to know the query variables used in current page, the you can do the following:

$data = array(
  'user'       => wp_get_current_user(),
  'query_vars' => $GLOBALS['wp']->query_vars
);

wp_localize_script( 'myscript', 'MyScriptData', $data );

Doing so in your script, the MyScriptData.user variable will be a JavaScript object with all the users information all the query variables.

This is valid for backend and frontend scripts (in other words: for both “sides”). There is no need for any additional JavaScript API just to fetch that information. PHP is enough if you use the proper ways to pass information from PHP to JS.

Backbone.js

Backbone.js, is a JavaScript framework that allows a (sort of) MVC development pattern with JavaScript. It was included in core with WP 3.5 – mainly to handle the media gallery.

This library is not a WordPress JavaScript API, because surely it allows a more powerful JavaScript development, but not a single WordPress-specific functions has been added to that library and it is the only current core usage of Backbone.js. The media library is more or less undocumented and has no public API. And AFAIK it is not planned to filled that gap. (More than happy to change/remove that statement – if someone can prove me wrong).

WP-API

As pointed out by Rarst and Brian Fegter, the WP API is going to be part of core (probably starting with WP 4.1).

But I have to say that it is not a JavaScript API. It just allows to connect a HTTP request to an application endpoint which is controlled by the WP-API. And the API fetches data from the database and returns it JSON formatted there. Example from the docs:

Want to get your site’s posts? Simply send a GET request to /wp-json/posts. Update user with ID 4? Send a POST request to /wp-json/users/4. Get all posts with the search term “awesome”? GET /wp-json/posts?filter[s]=awesome.

As HTTP requests and related JSON responses can be handled with any language that supports HTTP requests and JSON data format (among them PHP, Ruby, Python, ASP, etc.), the WP API main aim is to allow to get and set WordPress data from non-WP applications. That means from inside any application, not only WordPress.

Sure, since JavaScript is a language that can handle both HTTP requests and JSON format, you can use the WP-API from within WordPress JavaScript too. Someone is also working on a WP js client for that API, but

  • using wp_enqueue_script() + the Ajax API + WordPress PHP functions it is possible to retrieve all the information you need without any additional API. And since all the three “ingredients” are WP established standards, using them is not an “own solution”. It just makes use of standard solutions to do custom (and common) tasks, which is what this plugins development is all about.

  • it even is possible to use JavaScript to utilize the WP API. Just because the WP-API returns JSON, it does not make it a JavaScript API. There is no JavaScript function involved (a HTTP request is sent and a JSON reposnse is returned. Pretty much the same as what happens by using the AJAX API). Otherwise any service that returns JSON should be considered a WordPress JS API. The WP-API should be considered an external service API that returns JSON, and it may be the case that the site which consumes this JSON service is the same which provides it.

  • there isn’t a single thing that can be done with WP API that can not also be done by using the AJAX API. But there are a lot of things that can be done with the AJAX API. but not with the WP-API.

A note on the WP-API + Backbone.js

With Backbone.js, it is possible to get and save information in applications that support RESTful HTTP requests.

The problem is that WordPress, both in “regular” requests and in AJAX ones, is all but RESTful: It only supports $_GET and $_POST requests per default, and using the one or the other with the same URl ends up in … the same result.

On the contrary, the WP API is RESTful, so Backbone-based applications can take advantage of it for powerful JavaScript applications, but I would stay away from defining Backbone or WP API or Backbone + WP API as a JavaScript API for WordPress for things said above.

Leave a Comment