Platform Updates: Batching Calls, Privacy Settings, and IDs

Posted on by

We’ve made a few more updates to our APIs recently that we wanted to share with you.

The biggest update is a new query parameter that’s now available on all endpoints. The new parameter allows you to batch certain calls together, so you only need to make one request to get related data instead of two or three.

Since we released our APIs, we’d always return a list of related endpoints in the “meta” response with a series of links:

"meta": {
        "links": {
            "self": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238",
            "help": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/help",
            "site": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907",
            "replies": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/replies\/",
            "likes": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/likes\/"
},

Now, by passing ?meta=site, you can automatically get the data from the above endpoints in the original response. Let’s take a look at an example.

Say you’re loading a specific post but you want to know the name and description of the site the post was on. You can do this by making a call to: https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/posts/21238/?meta=site.

Which will give you a response like the following:

"meta": {
        "links": {
            "self": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238",
            "help": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/help",
            "site": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907",
            "replies": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/replies\/",
            "likes": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/21238\/likes\/"
        },
        "data": {
            "site": {
                "ID": 3584907,
                "name": "WordPress.com News",
                "description": "The latest news on WordPress.com and the WordPress community.",
                "URL": "http:\/\/en.blog.wordpress.com",
                "jetpack": false,
                "subscribers_count": 8396934,
                "meta": {
                    "links": {
                        "self": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907",
                        "help": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/help",
                        "posts": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/posts\/",
                        "comments": "https:\/\/public-api.wordpress.com\/rest\/v1\/sites\/3584907\/comments\/"
                    }
                },
                "is_private": false
            }
}

You can also pass multiple values in the meta query string. If you wanted the site endpoint and a list of likes for a post you can just pass "site,likes".

Two other updates we made are new responses:

  • We now include the value of privacy setting in the site information endpoint. A boolean value will be included as is_private.
  • We now include a global_ID response for all posts. This is a unique ID that you can use to identify posts if you are loading posts from multiple blogs in your application.

We hope you enjoy these updates. We’ll be making more improvements soon!

Developer Plugin 1.2.2 Released: New WP-CLI Command

Posted on by

Version 1.2.2 of the Developer plugin was recently released. The big feature of this release is a new WP-CLI command. If you’re not familiar with WP-CLI, it is “a set of command-line tools for managing WordPress installations.” These command-line tools let you do anything from download and install WordPress to manage options for your site. The command we’ve introduced will let you install and, optionally, activate the recommended plugins.

For example, the following will install and activate the Developer plugin and all the recommended plugins for WordPress.com VIP.

wp plugin install developer --activate
wp developer install-plugins --type=wpcom-vip --activate

As always, pull requests are welcome on Github. If you want to introduce a new WP-CLI subcommand or just stay up to date with the latest on the Developer plugin, join us there.

Metadata, Geotagging, and the REST API

Posted on by

WordPress.com now supports geotagging your posts. To enable the use of geotagging, find the new Location box in your Post Editor — you’ll see a “Turn On Location Tagging” button to enable it. Because of the improvements we’ve made in handling metadata, you can now geotag posts via the REST API.

Geo metadata keys are as follows:

geo_address
(required) A human-readable description string of the location name.
geo_latitude
(required) Latitude as a signed numeric value of degrees North of the Equator.
geo_longitude
(required) Longitude as a signed numeric value of degrees East of the Greenwich Meridian.
geo_public
(internal) If a post has a geolocation set, this will be true; it will be false if that information is unset.

If the address field is empty, the post will have a private location and the latitude and longitude values will be discarded.

The following code example demonstrates the array structure for creating a new post which is geotagged.

define( 'BEARER', 'YOUR_BEARER_TOKEN' );
define( 'SITE_ID', YOUR_SITE_ID );

$options = array( 'http' =>
		array(
		'ignore_errors' => true,
		'method' => 'POST',
		'header' => array (
			0 => 'authorization: Bearer ' . BEARER,
			1 => 'Content-Type: application/x-www-form-urlencoded',
			3 => 'Host: public-api.wordpress.com'
		),
		'content' => http_build_query(
			array (
				'title' => 'Hello Local',
				'content' => 'Hello. I am a new post created by the API.',
				'tags' => 'tests',
				'categories' => 'API',
				'metadata' => array(
					array(
						'operation' => 'add',
						'key' => 'geo_address',
						'value' => 'San Francisco, CA',
					),
					array(
						'operation' => 'add',
						'key' => 'geo_latitude',
						'value' => '37.7750',
					),
					array(
						'operation' => 'add',
						'key' => 'geo_longitude',
						'value' => '-122.4183',
					),
					array(
						'operation' => 'add',
						'key' => 'geo_public',
						'value' => true
					),
				),
			)
		),
	),
);

$context = stream_context_create( $options );
$response = file_get_contents(
	'https://public-api.wordpress.com/rest/v1/sites/' . SITE_ID . '/posts/new',
	false,
	$context
);
$response = json_decode( $response );

Once a post’s geo metadata has been updated, the post object that is returned to you will contain the geo data in an updated geo object, as well as in the metadata array.

stdClass Object
(
...skipped...
    [geo] => stdClass Object
        (
            [latitude] => 39.487085
            [longitude] => -101.425781
            [address] => San Francisco
        )
...skipped...
    [metadata] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 6784
                    [key] => geo_address
                    [value] => San Francisco
                )

            [1] => stdClass Object
                (
                    [id] => 6785
                    [key] => geo_latitude
                    [value] => 39.487085
                )

            [2] => stdClass Object
                (
                    [id] => 6786
                    [key] => geo_longitude
                    [value] => -101.425781
                )

            [3] => stdClass Object
                (
                    [id] => 6787
                    [key] => geo_public
                    [value] => 1
                )
        )
)

Custom post type and metadata support in the REST API

Posted on by

We’ve recently made some updates to the REST API which is available here on WordPress.com and for any Jetpack-enabled site that have the REST API module activated. The API now has full read and write support for custom post types and post metadata.

You can specify a post’s post type when you create or edit it. If you’re fetching a single post, you will receive it’s post type in the response. Of course, you can also specify a post type when fetching a series of posts. In all cases the parameter to use or look out for is type.

You can also query posts by metadata using the new meta_key and meta_value parameters. You can add, update, delete or retrieve a post’s metadata when creating, editing or getting a single post, using the new metadata parameter which accepts an array of metadata keys, ids, previous_values, values and operations, based on the operation you are trying to perform.

In order to enable your custom post types to work with the REST API on your Jetpack enabled sites, you will need to whitelist them using the new rest_api_allowed_post_types filter available in Jetpack, which is a simple array of the post type names that should be allowed to work with the API.

By default, all metadata keys are allowed in the API, as long as they are not protected keys. Any metadata key that starts with _ is by default protected. Protected metadata keys can, however, be accessed and edited by users with the edit_post_meta (used for editing and viewing), add_post_meta and delete_post_meta capabilities as appropriate for each operation. We’ve also added a filter rest_api_allowed_public_metadata that allows you to specifically whitelist certain metadata keys to be accessed by any user, even if that key is protected.

Here’s a quick rundown. If the user performing the request is unauthenicated, he or she will not be able to add, edit or delete any metadata; will be able to read any metadata for which the key doesn’t begin with _ but will not be able to read any metadata which begins with _ unless it is whitelisted.

If the user performing the request is authenticated and has the above listed capabilities, he or she, will be able to read, add, edit or delete any metadata, even if it begins with _ and is not whitelisted.

In order to make it easier for you to add support for custom post types and metadata in your own plugins and themes, we’ve also added a third filter jetpack_rest_api_compat in the main Jetpack file, which allows you to load additional files where you can then add all of your REST API compatibility code, using the filters above.

Because we love bbPress, we’ve bundled in support for bbPress and the REST API directly into Jetpack, so that you can read, write and edit bbPress forums, topics and replies right out of the box. You can also use this file as an example on how to bundle support in your own plugins or themes.

Check out our documentation, create an app, and get started today!
Let us know if you have any questions in the comments below.

Developer plugin 1.2 released: UI Improvements and New Plugins

Posted on by

Version 1.2 of the Developer plugin is hot off the press!

1.2 includes a host of UI improvements as well as two new plugins, Log Viewer by Markus Fischbacher, and Jetpack by Automattic, plus a new Jetpack constant,  JETPACK_DEV_DEBUG. This release aims to improve the usability of Developer by adding:

  • Detailed messages in case of an error while installing or activating a plugin
  • Plugin descriptions on installation steps, so it’s more clear what you’re installing actually does
  • A link to the plugin details page on installation steps
  • A more obvious button to close the post-install modal window

Also included are some behind the scenes improvements to make recommended plugins and constants more flexible down the road as we continue to add to the plugin.

If you’d like to stay up to date with the latest on Developer, please join us on Github where all feedback, plugin suggestions, bug reports, and pull requests are always welcome!

Meet Justin Shreve

Posted on by

Justin Shreve

Justin Shreve

Meet Justin Shreve: self-taught coder, cat daddy to Harris and Skylar, Google Summer of Code grad, and all around awesome guy.

What motivated you to become a developer? What do you like best about coding?

When I was little I used to sit in on the HTML classes that my parents would teach during the summers. I found it fascinating and wanted to learn more. By the next year I was answering questions that their students raised. From there I taught myself PHP and Javascript and eventually began working with WordPress.

Teaching himself PHP, probably.

Teaching himself PHP, probably.

I was so enthralled with how the different pieces worked together. That’s what really made me want to become a developer. To figure out how things were built, and how I could take them apart, rebuild them, and improve them.

The thing I like best about coding is there’s always something to do. Coding doesn’t get boring because there’s always a feature to add or a bug to fix.

Describe the killer app you’d build, if your wildest fantasy came true.

It’s a vague idea but I’d love to do some kind of augmented reality (AR) game. Maybe an app for something like Google’s Project Glass. I’ve always been interested in games and game design. I think AR and AR games could really be brought to a whole new level with the stuff that’s being developed. It’d be amazing to be a part of that and build a “killer app/game.”

If you could share just one piece of hard-won advice with young coders, what would it be?

Don’t be afraid to break stuff. It’s how you learn. Just jump in and start coding. There are plenty of resources available to you and plenty of people willing to help you learn.

Also, seriously consider playing with open source projects. I learned a lot more once I started working with WordPress and moved away from proprietary code bases.

Meet Justin Shreve is the second in our developer interview series. We’d like you to meet Beau Lebens, too.

Meet Beau Lebens

Posted on by

Hello there! Welcome to a new feature of the WordPress Developer Resources Blog — interviews! In this inaugural instalment, we’d like to formally introduce you to Mr. Beau Lebens, though he insists you can call him Beau. Beau is famous for many things, including Krav Maga, and instituting burrito Fridays at Automattic headquarters in San Francisco.

How did you get into working with WordPress and how long have you been at it?

Beau Lebens

Beau Lebens

I kept an eye on WordPress just out of casual interest more than anything else (in the beginning). The first time I really used it for something serious was to make a blog for a company I was working for at the time.

That was in 2005. (I had probably been following WordPress loosely for about a year before that.) When I left that company, I started a startup with a friend which was all based on WordPress (MU, as it was called at the time) and bbPress. It was called MyBabyOurBaby.com and was basically a shared scrapbooking site for families to save memories around a child.

While building that, I worked for about eight months, day and night on nothing but WordPress. I was trying to make it do a lot of things that it wasn’t supposed to, and trying to integrate with bbPress (which was really rough at the time), so it was a pretty huge learning curve. That exposure gave me pretty solid experience with WordPress though, and I was hooked. Once MyBabyOurBaby was built, but not really taking off, I started doing a lot of WP freelance work on the side. I ended up mostly working on performance and larger-scale sites since I had a bit of background in server management in addition to WP. That ended me up at Mashable.com for about six months, helping them get their site stable, building out some custom statistics/reporting systems and a few other plugins.

After that I ended up at Automattic and the rest is history :)

What’s the most important advice you can impart to a young person who wants to get into coding and development?

Dive right in. It’s just code, so you really can’t break anything too serious. Get a copy of an open source project in your language of choice (oh hai, WordPress.org!) and you can start pulling it apart to see how it works. Never be afraid to try something, even if you think it will probably break everything — that’s what “undo” is for. And backups. And source control. :)

What’s the most important challenge currently facing WordPress developers?

I think WordPress provides a lot of the components required to build amazing products (themes, plugins, entire web applications), including everything needed to make them secure. This is where the challenge comes in for developers — ensuring what they build is as secure as the core software is. Almost every security vulnerability or exploit that I hear about is via a plugin or theme. It’s up to WP developers to build software that lives up to the platform that it’s running on and to help ensure that we’re all running a safe, secure system. Having a good understanding of a few core concepts around security (especially within WP) can go a LONG way.

Knowing these two documents inside out and applying the ideas to your code will put you ahead of most other WordPress developers:

For more on Beau, check out his blog, Dented Reality, and follow him on Twitter.

Platform Updates: Posting Endpoints

Posted on by

We have made a few recent additions to our posting APIs that allow more control when creating posts.

You can now

  • Set a custom slug for the post permalink using the slug parameter.
  • Disable or enable the publicizing of posts, or only publicize to certain services (Twitter, Facebook, etc) using the publicize parameter.
  • Pass a custom message to the above publicize services using the publicize_message parameter.
  • Set the status of a post as “pending review” by passing pending to the status parameter.

When getting a post you can now

  • Find the featured image for a post using featured_image which will return a URL.

New Color Picker in WordPress 3.5

Posted on by

Some of you may have noticed the shiny new color picker in WordPress 3.5. This was a great example of collaboration between a commercial service and open source: we developed a color picker for WordPress.com to scratch our own itch, then offered it to WordPress.org. They then pushed us to make it so much better than it would have been otherwise. Everybody wins.

Find out more, including how to use it in your next WP project, on make/core: New Color Picker in WP 3.5.

Using the REST API with WordPress.org self-hosted sites via Jetpack

Posted on by

As of Jetpack 1.9, the WordPress.com REST API can now access self-hosted WordPress blogs with the Jetpack plugin installed.

Instead of just building for the WordPress.com platform, you can build awesome applications that interact with WordPress in general. Any applications built using the API for WordPress.com will automatically work with Jetpack-enabled sites running Jetpack 1.9 or higher.

Check out our documentation, create an app, and get started today!