XML-RPC and RESTful APIs: Breaking Down the WordPress Silo

Slide 1

Slide 1 text

XML-RPC and RESTful APIs: Breaking Down the WordPress Silo Max Cutler PDXWP July 2013

Slide 2

Slide 2 text

Who am I? •  http://maxcutler.com •  @maxcutler •  Core Contributor for XML-RPC in 3.4, 3.5 •  WordPress for Windows Phone •  Dev @ Microsoft –  Mobile app performance

Slide 3

Slide 3 text

Motivation Examples XML-RPC & WordPress Tips for plugin and theme authors REST & WordPress

Slide 4

Slide 4 text

MOTIVATION

Slide 5

Slide 5 text

Posts Media Comments Tweets CPTs The Silo

Slide 6

Slide 6 text

Break down the data silo

Slide 7

Slide 7 text

Cross-system interoperability

Slide 8

Slide 8 text

WordPress as Application Framework

Slide 9

Slide 9 text

EXAMPLES

Slide 10

Slide 10 text

Mobile Apps http://wordpress.org/mobile/

Slide 11

Slide 11 text

Offline Writing Applications Windows Live Writer, MarsEdit, ecto, etc.

Slide 12

Slide 12 text

Jetpack

Slide 13

Slide 13 text

Chicago Tribune News Apps Varnish Caching Unit Tests http://blog.apps.chicagotribune.com/2011/06/28/dont-break-the-homepage-using-unit-tests-to- validate-your-wordpress-varnish-caching-strategy/

Slide 14

Slide 14 text

Generate WordPress site using build tools https://github.com/scottgonzalez/grunt-wordpress github.com/jquery/api.jquery.com (XML files in git repo) grunt-wordpress (XML-RPC bridge) api.jquery.com (WordPress site)

Slide 15

Slide 15 text

External Search Django + Haystack + Solr

Slide 16

Slide 16 text

Editorial content production with multiple-site remote publishing Camayak WordPress InDesign NITF Drupal

Slide 17

Slide 17 text

WordPress Site Mirroring IXR_Client to push or pull content across servers

Slide 18

Slide 18 text

icanhas XML-RPC Internal Editorial CMS (ASP.NET) Site 1 Site 2 Site 3 … Site 50 http://bit.ly/10X68KN + WordCamp talks

Slide 19

Slide 19 text

Back office integration Public WordPress Site • Contact form • Pages • Comments • Users Company Firewall/ Intranet • CRM • Customer Support • Knowledge Base • Bug Tracker

Slide 20

Slide 20 text

XML-RPC & WORDPRESS

Slide 21

Slide 21 text

get_posts my_plugin_function Normal functions WordPress

Slide 22

Slide 22 text

RPC WordPress System XYZ wp.getPosts wp.editPost XML-RPC client

Slide 23

Slide 23 text

“Simple cross-platform distributed computing, based on the standards of the Internet.” xmlrpc.com

Slide 24

Slide 24 text

RPC using XML serialization

Slide 25

Slide 25 text

Sample Exchange - Request POST /xmlrpc.php HTTP/1.0 User-‐Agent: Max’s API Client Host: maxcutler.com Content-‐Type: text/xml wp.getUsersBlogs maxcutler w0rdPr3s$

Slide 26

Slide 26 text

Sample Exchange - Response HTTP/1.0 200 OK Content-‐Type: text/xml isAdmin 1 url http://www.maxcutler.com/ blogid 1 blogName Max Cutler xmlrpc http://www.maxcutler.com/xmlrpc.php

Slide 27

Slide 27 text

Libraries for every language •  PHP/WordPress – IXR •  Python – xmlrpclib •  Ruby – XMLRPC::Client •  Perl – RPC::XML •  C# - XML-RPC.NET •  Java – ws-xmlrpc •  JavaScript – Mimic, node-xmlrpc •  And many more…

Slide 28

Slide 28 text

xmlrpc.php •  WordPress.com •  On-by-default in WordPress 3.5 •  For 3.4 and below: –  –  Use “XML-RPC Modernization” plugin •  wp-includes/class-wpxmlrpc-server.php

Slide 29

Slide 29 text

History •  r1348 (May 2004) – xmlrpc.php born •  1.5 – Blogger, MovableType, metaWeblog, and pingback APIs •  2.2 - Pages •  2.5 – Categories, Custom Fields •  2.6 – Options/Settings •  2.7 – Comments •  3.1 – Media Library (read or upload)

Slide 30

Slide 30 text

History – 3.3 blogger.getUsersBlogs blogger.getUserInfo blogger.getPost blogger.getRecentPosts blogger.newPost blogger.editPost blogger.deletePost metaWeblog.newPost metaWeblog.editPost metaWeblog.deletePost metaWeblog.getPost metaWeblog.getRecentPosts metaWeblog.getCategories metaWeblog.newMediaObject metaWeblog.getUsersBlogs pingback.ping pingback.extensions mt.getCategoryList mt.getRecentPostTitles mt.getPostCategories mt.setPostCategories mt.publishPost mt.getTrackbackPings wp.getUsersBlogs wp.getAuthors wp.getPage wp.getPages wp.newPage wp.editPage wp.deletePage wp.getPageList wp.getPageTemplates wp.getPageStatusList wp.getCategories wp.getTags wp.newCategory wp.deleteCategory wp.suggestCategories wp.getCommentCount wp.getComment wp.getComments wp.newComment wp.getCommentStatusList wp.getOptions wp.setOptions wp.uploadFile wp.getMediaItem wp.getMediaLibrary wp.getPostFormats wp.getPostStatusList demo.sayHello demo.addTwoNumbers system.listMethods

Slide 31

Slide 31 text

Slide 32

Slide 32 text

History – 3.4 •  Unified post types •  Unified taxonomies •  More useful media •  Actions & filters •  Bug-fixes •  Unit tests (!!!) http://codex.wordpress.org/XML-RPC wp.getPost wp.getPosts wp.newPost wp.editPost wp.deletePost wp.getPostType wp.getPostTypes wp.getPostFormats wp.getPostStatusList wp.getTaxonomy wp.getTaxonomies wp.getTerm wp.getTerms wp.newTerm wp.editTerm wp.deleteTerm wp.getMediaItem wp.getMediaLibrary wp.uploadFile wp.getCommentCount wp.getComment wp.getComments wp.newComment wp.editComment wp.deleteComment wp.getCommentStatusList wp.getOptions wp.setOptions wp.getUsersBlogs wp.getAuthors

Slide 33

Slide 33 text

History – 3.5 •  Enabled-by-default •  New user-related methods – wp.getUser, wp.getUsers – wp.getProfile, wp.editProfile •  Post revisions – wp.getRevisions, wp.restoreRevision •  Post & taxonomy term searching •  Performance for multisite http://codex.wordpress.org/XML-RPC

Slide 34

Slide 34 text

Method analogies WordPress Core API XML-RPC Method get_posts wp.getPost, wp.getPosts wp_insert_post wp.newPost, wp.editPost get_taxonomy wp.getTaxonomy, wp.getTaxonomies get_terms wp.getTerm, wp.getTerms wp_insert_term wp.newTerm wp_update_term wp.editTerm get_post_types wp.getPostType, wp.getPostTypes get_comments wp.getComment, wp.getComments

Slide 35

Slide 35 text

Clients •  Language •  Standard Library •  3rd-party libraries & wrappers – PHP: IXR_Client (ships with WordPress) – Python: python-wordpress-xmlrpc – Node.js: node-wordpress – C#/.NET: JoeBlogs – Javascript: JS-XML-RPC-lib-for-WordPress – Objective-C: wpxmlrpc

Slide 36

Slide 36 text

Post Querying •  wp.getPosts – Filter •  post_type, s, number, offset, order, orderby – Fields •  Meta-fields: post, taxonomies, custom_fields •  Individual fields –  post_id, post_title, post_date, post_date_gmt, post_modified, post_modified_gmt, post_status, post_type, post_name, post_author, post_password, post_excerpt, post_content, link, comment_status, ping_status, sticky, post_format, terms, custom_fields, enclosure

Slide 37

Slide 37 text

Post Querying wp.getPosts( 0, username, password, array( ‘post_type’ => ‘product’, ‘orderby’ => ‘title’, ‘order’ => ‘ASC’ ), array( ‘post_title’, ‘date_modified_gmt’, ‘link’ ) )

Slide 38

Slide 38 text

Post Creation wp.newPost( 0, username, password, array( ‘post_title’ => ‘Hello world’, ‘post_content’ => …, ‘terms_names’ => array( ‘post_tag’ => array( ‘day1’ ), ‘category’ => array( ‘introductions’ ) ) ) )

Slide 39

Slide 39 text

Post Creation (2) wp.newPost( 0, username, password, array( ‘post_type’ => ‘product’, ‘post_title’ => ‘ACME’, ‘post_content’ => …, ‘custom_fields’ => array( array( ‘key’ => ‘price’, ‘value’ => 15 ) ) ) )

Slide 40

Slide 40 text

TIPS FOR PLUGIN/THEME AUTHORS

Slide 41

Slide 41 text

http://codex.wordpress.org/ XML-RPC_Support http://codex.wordpress.org/ XML-RPC_Extending

Slide 42

Slide 42 text

Add/remove methods xmlrpc_methods filter function mynamespace_subtractTwoNumbers( $args ) { $number1 = (int) $args[0]; $number2 = (int) $args[1]; return $number1 -‐ $number2; } function mynamespace_new_xmlrpc_methods( $methods ) { $methods['mynamespace.subtractTwoNumbers'] = 'mynamespace_subtractTwoNumbers'; return $methods; } add_filter( 'xmlrpc_methods', mynamespace_new_xmlrpc_methods');

Slide 43

Slide 43 text

Adjust return values •  xmlrpc_default_*_fields – post, posttype, taxonomy •  xmlrpc_prepare_* – post, post_type, taxonomy, term, media_item, comment, page •  xmlrpc_blog_options •  wp_handle_upload •  Use the source, Luke!

Slide 44

Slide 44 text

PSA: Omit Trailing “?>”

Slide 45

Slide 45 text

REST & WORDPRESS

Slide 46

Slide 46 text

REST •  REpresentational State Transfer –  Roy Fielding •  Leverage existing HTTP design & infrastructure –  Stateless –  Verbs: GET,POST,PUT,PATCH,DELETE –  Response codes –  Caching –  Content types – XML, JSON, HTML, MsgPack, etc. •  Represent entities as resources with canonical URI –  Manipulate resource documents to change state •  HATEOS –  Discover resources and resource actions using hypermedia (e.g. links) provided dynamically by API

Slide 47

Slide 47 text

Richardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html

Slide 48

Slide 48 text

RESTful APIs •  Every service has its own take on REST principles –  Authentication –  Content negotiation –  Versioning –  Presence of RPC actions –  Use of hypermedia or templated URIs –  Rate limiting –  And more… •  Each a snowflake –  “RESTful” client frameworks available for most languages and platforms –  Most services provide pre-built client libraries

Slide 49

Slide 49 text

WordPress.com API •  “REST” –  JSON-based hybrid RPC-RESTful design –  CRUD for posts, comments, tags, categories –  oAuth for private data •  Available since April 2012 –  October 2012 – Added to WP.org via Jetpack –  April 2013 - Added CPT & custom fields •  WP.com-specific features –  Likes, follows, notifications, reblogs –  Freshly Pressed http://developer.wordpress.com/docs/api/

Slide 50

Slide 50 text

WordPress.com API Console https://developer.wordpress.com/docs/api/console/

Slide 51

Slide 51 text

WP.com for Windows 8

Slide 52

Slide 52 text

Core RESTful API •  Ryan McCue – Google Summer of Code •  Standard RESTful API design –  /: Index –  /posts: Post Collection –  /posts/: Post –  /posts//revisions: Post Collection –  /posts//comments: Comment Collection –  /posts//comments/: Comment –  /taxonomies: Taxonomy Collection –  /taxonomies/: Taxonomy –  /taxonomies//terms: Term Collection –  /taxonomies//terms/: Term –  /users: User Collection –  /users/me: User –  /users/: User •  3.7 or 3.8? http://wordpress.org/plugins/json-rest-api/ https://github.com/rmccue/WP-API/ http://make.wordpress.org/core/tag/json-api/

Slide 53

Slide 53 text

SUMMARY

Slide 54

Slide 54 text

So, what should I use? •  Reach: XML-RPC –  Both WP.com & WP.org, including old versions –  Pluggable –  Existing client libraries •  WP.com integration: WP.com REST API –  Also an option if you use Jetpack –  Limited existing client libraries, but not too difficult to roll your own •  Future: WP.org RESTful API –  Help alpha test Ryan’s GSoC project –  If/when it reaches core, likely community effort to build client libraries