Rambling Talk given at http://2012.oc.wordcamp.org/ Supplemental information at http://mdawaffe.wordpress.com/2012/06/02/wordcamp-oc-restjson-api-talk/

1. WordPress APIs
Feeds, XML-RPC, APP, and “REST”
WordCamp OC - 2012/06/02 - Mike Adams

2. Hi
• Mike Adams = mdawaffe
• Automattic/WordPress.com: ~6 years
• WordPress developer: ~8 years
• Team Social Lead

3. Hi
• Mike Adams = mdawaffe
• Automattic/WordPress.com: ~6 years
• WordPress developer: ~8 years
• Team Social Lead
Links/Examples:
wp.me/p1s-3Z
pee one ess dash three ZEE

4. WordPress Data
over HTTP
• Feeds
• XML-RPC
• Atom Publishing Protocol
• “REST”

5. Evaluating
• Provides useful data/ways to manipulate
• Is easy to work with in any language
• Well documented
• Grokkable (human readable)
• Command line is king

6. Feeds
• RSS v. Atom: essentially the same
• Historically, RSS has gotten more love

7. Feeds: Features
• Get
• Posts, Pages
• Comments
• Can use normal WordPress query args
author_name=mdawaffe,
search=wordpress,
category_name=goats, page=2, ...

8. Feeds: Tools
• Command Line: curl
• PHP: SimplePie
http://simplepie.org/
• WordPress: fetch_feed()
Simple wrapper for SimplePie
• JS: It’s just XML?
DOM, jQuery, ...

9. Feeds: Examples
• Via JS, get most recent post titles:
jsfiddle.net/mdawaffe/ZQn5c/
• Via CLI, get URL of most recent post:
curl example.com/feed/ |
perl -pe 'BEGIN{$/=undef}
s/.*?<item>.*?<link>(.*?)<.*
/$1/s'
Not really CLI if you resort to Perl :)

10. Feeds: Examples
• Count posts by Marla that contain the
string “movie”.
curl example.com/feed/
?author_name=marla
&search=movie
| grep '<item>'
| wc -l
Nope: Won’t work

11. Feeds: Caveats
• Not always a perfect representation of
for-display content
• Never a good representation of
for-edit content
• Pagination
• Plugins that add structured data to feeds
may only touch RSS (not Atom)

12. Feeds: Evaluation
• Data: Posts, Comments Only. Read Only
• Easy: Meh - Libraries
• Docs: Lots of specs
• Grok: Mostly
• CLI: Not so easy

13. Feeds: Conclusion
• Quick way of reading basic data, but caveats
• Longstanding, standard formats
• Parsers available in every language
• For WordPress, RSS > Atom

14. XML-RPC
• Remote Procedure Call = Function based
• Developed by Dave Winer in 1999
• xmlrpc.scripting.com/spec.html

15. XML-RPC: Request
POST /xmlrpc.php HTTP/1.1
HOST: example.com
Content-Type: text/xml
Content-Length: 311
<?xml version="1.0"?>
<methodCall>
<methodName>wp.getPosts</methodName>
<params>
<param>
<value>
<array>
<data>
<value><int>0</int></value>
<value><string>username</string></value>
<value><string>password</string></value>
</data>
</array>
</value>
</param>
</params>
</methodCall>

16. XML-RPC: Response
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 27000
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<array>
<data>
<value>
<struct>
<member><name>post_id</name><value><string>26</
string></value></member>
<member><name>post_title</name><value><string>Space
Monkey!</string></value></member>
...
</struct>
</value>
<value>
...

17. XML-RPC: WordPress
• WordPress offers considerable
functionality: Read and Write
• Requires Authentication
• Supported on all WordPress sites
(Opt-in for non-WordPress.com sites)
• Poorly Documented
• Highly Extensible (via Plugin)

18. XML-RPC: Features
• Get/Create/Edit/Delete
• Posts, Pages
• Comments
• Terms, Taxonomies
• Options
• Media Uploads

19. XML-RPC: Auth
• All (most) XML-RPC calls require
authentication
• WordPress.ORG
• Username/Password
• Extensible via Plugin

20. XML-RPC: Auth
• All (most) XML-RPC calls require
authentication
• WordPress.COM
• Username/Password
• OAuth2

21. XML-RPC: Docs
• XML-RPC is just a communication spec
• Standard sets of Remote Procedures:
Blogger, MoveableType, MetaWeblog, ...
• WordPress supports them all!
• codex.wordpress.org/XML-RPC_Support
• wp-includes/class-wp-xmlrpc-server.php

22. XML-RPC: Extensible
• New Remote Procedures can be added
with the xmlrpc_methods filter
• Hooked function:
• accepts array of arguments
• returns most anything
• XML parsing/serializing done by WordPress

23. XML-RPC: Tools
• Command Line: Hard
• PHP: xmlrpc_encode_request()
• WordPress: WP_HTTP_IXR_Client
• JS: Mimic mimic-xmlrpc.sourceforge.net

24. XML-RPC: Example
$x = new WP_HTTP_IXR_Client($URL);
$x->query( ‘wp.newPage’, array(
0, ‘user’, ‘password’,
array(
‘title’ => ‘WordCamp’,
‘description’ => ‘OC, Baby!’
),
1,
));

25. XML-RPC: Caveats
• Never a true representation of for-display
content
• Usually a true representation of for-edit
content
• Pagination impossible (until 3.4)

26. XML-RPC: Evaluation
• Data: Lots of functionality
• Easy: Meh - Libraries
• Docs: No
• Grok: No
• CLI: No

27. XML-RPC: Conclusion
• Pros
• WordPress offers lots of functionality
• Easy to extend
• Cons
• Caveats
• Verbose XML
• Poorly Documented

28. APP
• Atom Publishing Protocol
• RESTful - object based
• Posts are represented as Atom Feed entries
• tools.ietf.org/html/rfc5023

29. APP: WordPress
• WordPress offers limited functionality
• Requires Authentication
• Supported on all WordPress sites
(Opt-in for non-WordPress.com sites)
• Poorly Documented
• Harder to extend than XML-RPC

30. APP: Features
• Get/Create/Edit/Delete
• Posts, Pages
• Media Uploads

31. APP: Auth
• All APP calls require authentication
• BASIC (Username/Password)
• Extensible via Plugin

32. APP: Example

33. APP: Example
...

34. APP: Evaluation
• Data: Posts only
• Easy: Not really. At least it’s XML.
• Docs: No
• Grok: Looks like a feed
• CLI: No

35. APP: Conclusion
• Pro: Aesthetically cool
• Cons
• Not very well supported in WordPress
• Hard to extend
• Poorly documented
• Don’t bother unless you are heavily
invested in APP elsewhere already

36. “REST”ful JSON
• WordPress.COM has launched a new
RESTful JSON API
• Soon in Jetpack
• Will likely be in core (3.6?)

37. “REST”ful JSON
• Fairly full featured
• Public data does not require authentication
• Private data requires OAuth2
• True representation of both
for-display, and for-edit content
• Well documented

38. JSON: Features
• Get/Create/Edit/Delete
• Posts, Pages
• Comments
• Terms, Taxonomies
• Media Uploads

39. JSON: “REST”
https://public-api.wordpress.com/rest/v1/sites/$site
• Read: GET /posts/$post_id
• Create: POST /posts/new
• Update: POST /posts/$post_id
• Delete: POST /posts/$post_id/delete
POST requests can be JSON or form encoded

40. JSON: Docs
• Dynamically generated: always up to date
• developer.wordpress.com/docs/api/
• Append “/help” to any API URL
• API Console: AMAZING!
developer.wordpress.com/docs/api/console/

41. JSON: Tools
• Command Line: curl
• PHP: file_get_contents()
• WordPress: wp_remote_request()
• JS:Yes
• Any language that can make remote HTTP
requests and understand JSON(P)

42. JSON: Examples
• Get most recent post
public-api.wordpress.com/rest/v1/sites/
en.blog.wordpress.com/posts/?number=1
jsfiddle.net/mdawaffe/hLWdH/
• Get a post’s likes
public-api.wordpress.com/rest/v1/sites/
en.blog.wordpress.com/posts/11235/likes/
jsfiddle.net/mdawaffe/QgPqV/

43. JSON: Examples
• Create a Post
curl --data 'title=WCOC'
--data 'content=Rocks'
-H 'Authorization:
BEARER *SECRET*'
https://public-
api.wordpress.com/rest/v1/
sites/mdawaffe.wordpress.com/
posts/new

44. JSON: Evaluation
• Data: Not as fully featured as XML-RPC
• Easy:Yes
• Docs:Yes!
• Grok:Yes
• CLI:Yes!

45. JSON: Conclusion
• Pros
• Easiest to use
• Built in up-to-date documentation
• True representation of for-display and
for-edit content
• Con:
• Not as full featured as XML-RPC (yet!)

46. Bye
• Mike Adams = mdawaffe

47. Bye
• Mike Adams = mdawaffe
• Thanks!