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

Transcript

1. XML-RPC and RESTful APIs: Breaking Down the WordPress Silo Max Cutler PDXWP July 2013
2. 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
3. Motivation Examples XML-RPC & WordPress Tips for plugin and theme authors REST & WordPress
4. MOTIVATION
5. Posts Media Comments Tweets CPTs The Silo
6. Break down the data silo
7. Cross-system interoperability
8. WordPress as Application Framework
9. EXAMPLES
10. Mobile Apps http://wordpress.org/mobile/
11. Offline Writing Applications Windows Live Writer, MarsEdit, ecto, etc.
12. Jetpack
13. 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/
14. 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)
15. External Search Django + Haystack + Solr
16. Editorial content production with multiple-site remote publishing Camayak WordPress InDesign NITF Drupal
17. WordPress Site Mirroring IXR_Client to push or pull content across servers
18. icanhas XML-RPC Internal Editorial CMS (ASP.NET) Site 1 Site 2 Site 3 … Site 50 http://bit.ly/10X68KN + WordCamp talks
19. Back office integration Public WordPress Site • Contact form • Pages • Comments • Users Company Firewall/ Intranet • CRM • Customer Support • Knowledge Base • Bug Tracker
20. XML-RPC & WORDPRESS
21. get_posts my_plugin_function Normal functions WordPress
22. RPC WordPress System XYZ wp.getPosts wp.editPost XML-RPC client
23. “Simple cross-platform distributed computing, based on the standards of the Internet.” xmlrpc.com
24. RPC using XML serialization
25. Sample Exchange - Request POST  /xmlrpc.php  HTTP/1.0     User-­‐Agent:  Max’s  API  Client   Host:  maxcutler.com     Content-­‐Type:  text/xml     <?xml  version="1.0"?>   <methodCall>          <methodName>wp.getUsersBlogs</methodName>          <params>                  <param><value>maxcutler</value></param>                  <param><value>w0rdPr3s$</value></param>          </params>   </methodCall>  
26. Sample Exchange - Response HTTP/1.0  200  OK   Content-­‐Type:  text/xml       <?xml  version="1.0"?>   <methodResponse>          <params><param><value><array><data><value><struct>                  <member><name>isAdmin</name>                      <value><boolean>1</boolean></value></member>                  <member><name>url</name>                          <value>http://www.maxcutler.com/</value></member>                  <member><name>blogid</name>                          <value>1</value></member>                  <member><name>blogName</name>                          <value>Max  Cutler</value></member>                    <member><name>xmlrpc</name>                          <value>http://www.maxcutler.com/xmlrpc.php</value></member>          </struct></value></data></array></value></param></params>   </methodResponse>  
27. 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…
28. xmlrpc.php •  WordPress.com •  On-by-default in WordPress 3.5 •  For 3.4 and below: –  –  Use “XML-RPC Modernization” plugin •  wp-includes/class-wp- xmlrpc-server.php
29. 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)
30. 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
31. 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
32. 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
33. 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
34. 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
35. 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
36. 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  
37. Post Querying wp.getPosts(  0,  username,  password,          array(                ‘post_type’  =>  ‘product’,              ‘orderby’  =>  ‘title’,              ‘order’  =>  ‘ASC’            ),          array(  ‘post_title’,              ‘date_modified_gmt’,  ‘link’  )   )  
38. Post Creation wp.newPost(  0,  username,  password,      array(          ‘post_title’  =>  ‘Hello  world’,          ‘post_content’  =>  …,          ‘terms_names’  =>  array(              ‘post_tag’  =>  array(  ‘day1’  ),              ‘category’  =>  array(  ‘introductions’  )          )      )   )  
39. 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  )          )      )   )  
40. TIPS FOR PLUGIN/THEME AUTHORS
41. http://codex.wordpress.org/ XML-RPC_Support http://codex.wordpress.org/ XML-RPC_Extending
42. 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');  
43. 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!
44. PSA: Omit Trailing “?>”
45. REST & WORDPRESS
46. 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
47. Richardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html
48. 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
49. 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/
50. WordPress.com API Console https://developer.wordpress.com/docs/api/console/
51. WP.com for Windows 8
52. Core RESTful API •  Ryan McCue – Google Summer of Code •  Standard RESTful API design –  /: Index –  /posts: Post Collection –  /posts/<id>: Post –  /posts/<id>/revisions: Post Collection –  /posts/<id>/comments: Comment Collection –  /posts/<id>/comments/<comment>: Comment –  /taxonomies: Taxonomy Collection –  /taxonomies/<tax>: Taxonomy –  /taxonomies/<tax>/terms: Term Collection –  /taxonomies/<tax>/terms/<term>: Term –  /users: User Collection –  /users/me: User –  /users/<user>: 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/
53. SUMMARY
54. 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
55. DEMOS + Q&A
56. Thanks!