Share
Embed
XML-RPC and RESTful APIs: Breaking Down the WordPress Silo
Max Cutler
July 15, 2013
Transcript
56 slides
-
XML-RPC and RESTful APIs: Breaking Down the WordPress Silo Max
Cutler PDXWP July 2013 -
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 -
Motivation Examples XML-RPC & WordPress Tips for plugin and theme
authors REST & WordPress -
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) -
icanhas XML-RPC Internal Editorial CMS (ASP.NET) Site 1 Site 2
Site 3 … Site 50 http://bit.ly/10X68KN + WordCamp talks -
Back office integration Public WordPress Site • Contact form • Pages • Comments
• Users Company Firewall/ Intranet • CRM • Customer Support • Knowledge Base • Bug Tracker -
“Simple cross-platform distributed computing, based on the standards of the
Internet.” xmlrpc.com -
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> -
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> -
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… -
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 -
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) -
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 -
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 -
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 -
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 -
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 -
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 -
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 -
Post Querying wp.getPosts( 0, username, password,
array( ‘post_type’ => ‘product’, ‘orderby’ => ‘title’, ‘order’ => ‘ASC’ ), array( ‘post_title’, ‘date_modified_gmt’, ‘link’ ) ) -
Post Creation wp.newPost( 0, username, password, array(
‘post_title’ => ‘Hello world’, ‘post_content’ => …, ‘terms_names’ => array( ‘post_tag’ => array( ‘day1’ ), ‘category’ => array( ‘introductions’ ) ) ) ) -
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 ) ) ) ) -
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'); -
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! -
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 -
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 -
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/ -
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/ -
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