Baking semantic web access into non-geek services

1. A REST API for Content Management baking semantic web access into non-geek services

2. Stephen Howard Athens, Georgia [email_address] http://enterity.com

3. a presentation in 3 acts

4. a presentation in 3 acts what is renao?

5. a presentation in 3 acts what is renao? the renao API

6. a presentation in 3 acts what is renao? the renao API building a community

7. act 1 what is renao?

8. renao [ren- ah -oh], adj. what is renao? From Mandarin. Lierally " hot " but also includes "noisy," "making noise," and "stirring up trouble.” In China the term is a positive, implying " lively, festive, happy, noisy " - especially noisy! from In Other Words by Christopher J. Moore http://myrenao.com/what

9. renao [ren- ah -oh], n. A hosted content management service http://myrenao.com

10. content management what is renao?

11. content management what is renao?

12. design management what is renao?

13. design management what is renao?

14. flexible results what is renao?

15. three guiding principles what is renao?

16. three guiding principles what is renao? content has structure

17. three guiding principles what is renao? content has structure URLs are nouns

18. three guiding principles what is renao? content has structure URLs are nouns templates for many formats

19. 1: content has structure what is renao: 3 guiding principles

20. 1: content has structure what is renao: 3 guiding principles most organizations have collections of things (resources), physical or conceptual, that they want to publish online

21. 1: content has structure what is renao: 3 guiding principles most organizations have collections of things (resources), physical or conceptual, that they want to publish online these resources usually have a consistent set of structured or semi-structured information

22. 1: content has structure what is renao: 3 guiding principles most organizations have collections of things (resources), physical or conceptual, that they want to publish online these resources usually have a consistent set of structured or semi-structured information let them use these structures they’re already familiar with when adding content to their sites

23. 1: content has structure what is renao: 3 guiding principles most organizations have collections of things (resources), physical or conceptual, that they want to publish online these resources usually have a consistent set of structured or semi-structured information let them use these structures they’re already familiar with when adding content to their sites a better format for machines to understand than flat html pages.

24. 2: URL s are nouns what is renao: 3 guiding principles

25. 2: URL s are nouns what is renao: 3 guiding principles URL s can refer to a specific resource http://example.com/about_us http://example.com/blog/designing_an_api

26. 2: URL s are nouns what is renao: 3 guiding principles or a list of resources URL s can refer to a specific resource http://example.com/Articles http://example.com/about_us http://example.com/blog/designing_an_api

27. 2: URL s are nouns what is renao: 3 guiding principles use query parameters to refine your results or a list of resources URL s can refer to a specific resource /Articles?name[like]=perl&sort=publish_date,desc http://example.com/Articles http://example.com/about_us http://example.com/blog/designing_an_api

28. 2: URL s are nouns what is renao: 3 guiding principles or use the full-text search parameter instead http://example.com?q=perl http://example.com/blog?q=perl use query parameters to refine your results or a list of resources URL s can refer to a specific resource /Articles?name[like]=perl&sort=publish_date,desc http://example.com/Articles http://example.com/about_us http://example.com/blog/designing_an_api

29. 2: URL s are nouns what is renao: 3 guiding principles or use the full-text search parameter instead http://example.com?q=perl http://example.com/blog?q=perl special shortcut URL s for tags use query parameters to refine your results or a list of resources URL s can refer to a specific resource http://example.com/Articles/t/perl http://example.com/blog/t/perl /Articles?name[like]=perl&sort=publish_date,desc http://example.com/Articles http://example.com/about_us http://example.com/blog/designing_an_api

30. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request:

31. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request: /article.html what kind of resource is it?

32. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request: /resource.html can’t find a template for that resource type? look for a template for the parent resource type. /article.html what kind of resource is it?

33. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request: /articles.html is the request for a list of resources? /resource.html can’t find a template for that resource type? look for a template for the parent resource type. /article.html what kind of resource is it?

34. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request: check for template / blog/article.html otherwise use /article.html what collection is the resource in? /articles.html is the request for a list of resources? /resource.html can’t find a template for that resource type? look for a template for the parent resource type. /article.html what kind of resource is it?

35. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request: ends in .xml? -> use /article.xml is there a specific extension on the url? check for template / blog/article.html otherwise use /article.html what collection is the resource in? /articles.html is the request for a list of resources? /resource.html can’t find a template for that resource type? look for a template for the parent resource type. /article.html what kind of resource is it?

36. a presentation in 3 acts what is renao? the renao API building a community

37. act 2 the renao API

38. API objectives the renao API

39. API objectives the renao API access your own site

40. API objectives the renao API access your own site write software for others to use

41. API objectives the renao API access your own site write software for others to use your site is your API, no special urls

42. API objectives the renao API access your own site write software for others to use your site is your API, no special urls manage content and design

43. API objectives the renao API access your own site write software for others to use your site is your API, no special urls manage content and design single authentication scheme

44. 1: access your own site the renao API: objectives

45. 1: access your own site the renao API: objectives update your site to reflect activities around the web

46. 1: access your own site the renao API: objectives update your site to reflect activities around the web update other sites and services to reflect changes on your site

47. 1: access your own site the renao API: objectives update your site to reflect activities around the web update other sites and services to reflect changes on your site integrate with your own software projects

48. 1: access your own site the renao API: objectives update your site to reflect activities around the web update other sites and services to reflect changes on your site integrate with your own software projects tools and shortcuts that better match how you work.

49. 2: write software for others the renao API: objectives

50. 2: write software for others the renao API: objectives integrate Renao into existing software

51. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools

52. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets

53. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets browser plugins

54. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets browser plugins desktop apps

55. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets browser plugins desktop apps start a business

56. 3: your site is your API the renao API: objectives

57. 3: your site is your API the renao API: objectives Minimize the amount of extra code to support an API

58. 3: your site is your API the renao API: objectives Minimize the amount of extra code to support an API Minimize the number of API-specific urls

59. 3: your site is your API the renao API: objectives Minimize the amount of extra code to support an API Minimize the number of API-specific urls Use REST so talking to API users is nearly the same as talking to site visitors

60. 4: manage content and design the renao API: objectives

61. 4: manage content and design the renao API: objectives provide alternative interfaces for site owners

62. 4: manage content and design the renao API: objectives provide alternative interfaces for site owners desktop apps for richer design file editing

67. 4: manage content and design the renao API: objectives Caveat managing design files will probably violate the “no special urls” API rule.

69. 5: single authentication scheme the renao API: objectives

70. 5: single authentication scheme the renao API: objectives OAuth

71. 5: single authentication scheme the renao API: objectives OAuth 3-legged provide access on behalf of another user never have to ask for or store the user’s username and password User grants you an access-token which they have the power to revoke at a later date

72. 5: single authentication scheme the renao API: objectives OAuth 2-legged skip access-token dance send token-less OAuth requests for resources on your own sites 3-legged provide access on behalf of another user never have to ask for or store the user’s username and password User grants you an access-token which they have the power to revoke at a later date

73. single authentication scheme the renao API: objectives http://oauth.net/core/1.0

74. integrating the API the renao API session cleanup PerlCleanupHandler logging PerlLogHandler code written with REST in mind the main event PerlResponseHandler cookies or OAuth? initialize session PerlAccessHandler map url to resource(s) PerlTransHandler request_method browser fix-up map domain to site and account PerlInitHandler for API compatibility for all requests apache request cycle

75. using the renao API the renao API

76. using the renao API actions are HTTP Requests the renao API

77. using the renao API actions are HTTP Requests GET, HEAD, PUT, POST, DELETE the renao API

78. using the renao API actions are HTTP Requests GET, HEAD, PUT, POST, DELETE act on the URLs on your site the renao API

79. using the renao API actions are HTTP Requests GET, HEAD, PUT, POST, DELETE act on the URLs on your site OAuth for tasks that require authorization the renao API

80. using the renao API actions are HTTP Requests GET, HEAD, PUT, POST, DELETE act on the URLs on your site OAuth for tasks that require authorization account with developer key and passcode the renao API

81. sometimes you can get stuff done without authenticating the renao API: examples <h3> <a href= &quot;http://myrenao.com/discuss&quot; class= &quot;recent_topics&quot; > Recent Community Discussion Topics </a> <img src= &quot;/graphics/icons/go.png&quot; alt= &quot;go&quot; /> </h3> <h3> <a href= &quot; http://enterity.myrenao.com/blog &quot; class= &quot;recent_topics&quot; > Recent Blog Posts </a> <img src= &quot;/graphics/icons/go.png&quot; alt= &quot;go&quot; /> </h3> (1 of 3)

82. sometimes you can get stuff done without authenticating the renao API: examples // JSONP request with jQuery ----------------- Widget.RecentTopics = function( link ) { var baseurl_regex = new RegExp ( &quot;(http://[^/]+)&quot; ); var baseurl = link .href. match (baseurl_regex)[ 0 ]; $. getJSON ( link .href + '.jsonp?jsoncallback=?' , function( resources ){ for( var i = 0 ; i < resources .length; i ++ ) { var name = resources [i].subject || resources [i].name; $( link ). parent ().after( '<h4><a href=&quot;' + baseurl + resources [ i ].uri+ '&quot;>' + name + '</a></h4>’ ); } }) } // hook into the html ----------------- $ (function(){ $ ( 'a.recent_topics' ). each (function(){ Widget.RecentTopics ( this ); }); }); (2 of 3)

83. sometimes you can get stuff done without authenticating the renao API: examples [% # template: collection.jsonp ---- cgi . param ( 'jsoncallback' ); ‘(‘ ; # get the 10 most recent resources from this collection ---- USE Resources ; resources = Resources . retrieve ( 'Resource' , { inclusive => 1 , range => { offset => 0 , limit => 10 }, sort => [ 'publish_date' , 'desc' ], conditions => [ 'in' , 'collections' , collection .id] }); # output each resource in json format ---- FOREACH resource = resources ; PROCESS resource.json ; ',' UNLESS loop . last ; END; %] ) (3 of 3)

84. using Perl and Net::OAuth the renao API: examples use Net::OAuth ; use LWP::UserAgent ; use HTTP::Request::Common ; use Digest::MD5 qw( md5_hex ); my $site = 'stephen.myrenao.com' ; my $url = '/blog/Articles.json'; my $oauth_consumer_key = '848b9908df07dcdcb' ; my $oauth_consumer_secret = '7aeaded3671776407' ; # create OAuth Signature ----------------- my $oauth = Net::OAuth -> request ( 'consumer' )-> new ( request_url => $url , request_method => 'POST' , consumer_key => $oauth_consumer_key , consumer_secret => $oauth_consumer_secret , signature_method => 'HMAC-SHA1' , timestamp => time , nonce => md5_hex ( $oauth_consumer_key , time ), ); $oauth -> sign ; (1 of 2)

85. using Perl and Net::OAuth the renao API: examples # make HTTP Request ----------------- my $response = LWP::UserAgent -> new -> request ( POST &quot;http:// $site$url &quot; , Authorization => $oauth -> to_authorization_header , Content => { alias => 'testing_oauth' , name => 'testing my api' , body => 'This is a test of the Renao API' , commentable => 1 } ); # handle HTTP Response ----------------- print $response -> is_success ? &quot;successfully posted to site &quot; : &quot;something went wrong ” ; print $response -> status_line . &quot; ” . $response -> decoded_content . &quot; &quot; ; (2 of 2)

86. future API plans the renao API

87. future API plans the renao API accept data in more formats

88. future API plans the renao API accept data in more formats use headers to determine default response format

89. future API plans the renao API accept data in more formats use headers to determine default response format add device/screen-size detection for template selection

90. 1: accept data in more formats the renao API: future plans Check the content-type header on requests and parse body appropriately.

92. 2: use headers to determine default response format No format extension on the url? Use HTTP Accept header to determine response format the renao API: future plans http://example.com/about_us

93. 3: device/screen-size detection the renao API: future plans

94. 3: device/screen-size detection the renao API: future plans All devices use the same urls and domains

95. 3: device/screen-size detection the renao API: future plans All devices use the same urls and domains Use HTTP User-Agent header to look up templates particular for the device or class of device

96. 3: device/screen-size detection the renao API: future plans All devices use the same urls and domains Use HTTP User-Agent header to look up templates particular for the device or class of device Eliminates the need to maintain multiple copies or interfaces to your content for different devices

97. a presentation in 3 acts what is renao? the renao API building a community

98. act 3 building a community

99. examples building a community mashups Google Maps themes plugins Wordpress web apps desktop clients twitter desktop photo app integration web mashups extended services (printing) flickr

100. why build a community? building a community

101. why build a community? power users (designers and developers) can amplify and spread your work building a community

102. why build a community? power users (designers and developers) can amplify and spread your work service users can help each other out to excel at using the service to accomplish their goals building a community

103. why build a community? power users (designers and developers) can amplify and spread your work service users can help each other out to excel at using the service to accomplish their goals provides a group of people passionate about the service that won’t hesitate to provide an ongoing reality-check to you building a community

104. “ create more value than you capture” - Tim O’Reilly building a community

105. how to attract a community? some ideas building a community

106. how to attract a community? some ideas provide an online venue for the community to gather building a community

107. how to attract a community? some ideas provide an online venue for the community to gather cultivate an atmosphere of helpfulness among service users building a community

108. how to attract a community? some ideas provide an online venue for the community to gather cultivate an atmosphere of helpfulness among service users affiliate program building a community

109. how to attract a community? some ideas provide an online venue for the community to gather cultivate an atmosphere of helpfulness among service users affiliate program provide features that will attract power users building a community

110. features for power users ideas for designers building a community

111. features for power users ideas for designers allow for complete design flexibility building a community

112. features for power users ideas for designers allow for complete design flexibility user-contributed themes gallery building a community

113. features for power users ideas for designers allow for complete design flexibility user-contributed themes gallery free “project starter” sites for new client sites building a community

114. features for power users ideas for developers building a community

115. features for power users ideas for developers an API that is easy to understand and write for building a community

116. features for power users ideas for developers an API that is easy to understand and write for good API documentation building a community

117. features for power users ideas for developers an API that is easy to understand and write for good API documentation low barriers to getting started building a community

118. a presentation in 3 acts what is renao? the renao API building a community fin.

119. Thanks http://myrenao.com [email_address]

120. discussion: how do you attract a community around a service? http://myrenao.com [email_address]