A REST API for Content Management

3,936 views

Published on

Baking semantic web access into non-geek services

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
3,936
On SlideShare
0
From Embeds
0
Number of Embeds
7
Actions
Shares
0
Downloads
29
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • A REST API for Content Management

    1. 1. A REST API for Content Management baking semantic web access into non-geek services
    2. 2. Stephen Howard Athens, Georgia [email_address] http://enterity.com
    3. 3. a presentation in 3 acts
    4. 4. a presentation in 3 acts what is renao?
    5. 5. a presentation in 3 acts what is renao? the renao API
    6. 6. a presentation in 3 acts what is renao? the renao API building a community
    7. 7. act 1 what is renao?
    8. 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. 9. renao [ren- ah -oh], n. A hosted content management service http://myrenao.com
    10. 10. content management what is renao?
    11. 11. content management what is renao?
    12. 12. design management what is renao?
    13. 13. design management what is renao?
    14. 14. flexible results what is renao?
    15. 15. three guiding principles what is renao?
    16. 16. three guiding principles what is renao? content has structure
    17. 17. three guiding principles what is renao? content has structure URLs are nouns
    18. 18. three guiding principles what is renao? content has structure URLs are nouns templates for many formats
    19. 19. 1: content has structure what is renao: 3 guiding principles
    20. 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. 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. 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. 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. 24. 2: URL s are nouns what is renao: 3 guiding principles
    25. 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. 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. 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. 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. 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. 30. 3: templates for many formats what is renao: 3 guiding principles how renao picks from your templates for a given request:
    31. 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. 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. 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. 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. 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. 36. a presentation in 3 acts what is renao? the renao API building a community
    37. 37. act 2 the renao API
    38. 38. API objectives the renao API
    39. 39. API objectives the renao API access your own site
    40. 40. API objectives the renao API access your own site write software for others to use
    41. 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. 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. 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. 44. 1: access your own site the renao API: objectives
    45. 45. 1: access your own site the renao API: objectives update your site to reflect activities around the web
    46. 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. 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. 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. 49. 2: write software for others the renao API: objectives
    50. 50. 2: write software for others the renao API: objectives integrate Renao into existing software
    51. 51. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools
    52. 52. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets
    53. 53. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets browser plugins
    54. 54. 2: write software for others the renao API: objectives integrate Renao into existing software create convenience tools bookmarklets browser plugins desktop apps
    55. 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. 56. 3: your site is your API the renao API: objectives
    57. 57. 3: your site is your API the renao API: objectives Minimize the amount of extra code to support an API
    58. 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. 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. 60. 4: manage content and design the renao API: objectives
    61. 61. 4: manage content and design the renao API: objectives provide alternative interfaces for site owners
    62. 62. 4: manage content and design the renao API: objectives provide alternative interfaces for site owners desktop apps for richer design file editing
    63. 63. 4: manage content and design the renao API: objectives <ul><li>provide alternative interfaces for site owners </li></ul><ul><li>desktop apps for richer design file editing </li></ul><ul><ul><li>image editors </li></ul></ul>
    64. 64. 4: manage content and design the renao API: objectives <ul><li>provide alternative interfaces for site owners </li></ul><ul><li>desktop apps for richer design file editing </li></ul><ul><ul><li>image editors </li></ul></ul><ul><ul><li>syntax highlighters </li></ul></ul>
    65. 65. 4: manage content and design the renao API: objectives <ul><li>provide alternative interfaces for site owners </li></ul><ul><li>desktop apps for richer design file editing </li></ul><ul><ul><li>image editors </li></ul></ul><ul><ul><li>syntax highlighters </li></ul></ul><ul><ul><li>file upload progress indicators </li></ul></ul>
    66. 66. 4: manage content and design the renao API: objectives <ul><li>provide alternative interfaces for site owners </li></ul><ul><li>desktop apps for richer design file editing </li></ul><ul><ul><li>image editors </li></ul></ul><ul><ul><li>syntax highlighters </li></ul></ul><ul><ul><li>file upload progress indicators </li></ul></ul><ul><li>implement features I wouldn’t think of, don’t have time for, or don’t want </li></ul>
    67. 67. 4: manage content and design the renao API: objectives Caveat managing design files will probably violate the “no special urls” API rule.
    68. 68. 4: manage content and design the renao API: objectives <ul><li>Caveat </li></ul><ul><li>managing design files will probably violate the “no special urls” API rule. </li></ul><ul><li>normal graphics, scripts and css directories should be: </li></ul><ul><ul><li>fast: </li></ul></ul><ul><ul><li>no permission checks </li></ul></ul><ul><ul><li>minimal server side scripting </li></ul></ul><ul><ul><li>potentially: </li></ul></ul><ul><ul><li>distributable across a CDN </li></ul></ul>
    69. 69. 5: single authentication scheme the renao API: objectives
    70. 70. 5: single authentication scheme the renao API: objectives OAuth
    71. 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. 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. 73. single authentication scheme the renao API: objectives http://oauth.net/core/1.0
    74. 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. 75. using the renao API the renao API
    76. 76. using the renao API actions are HTTP Requests the renao API
    77. 77. using the renao API actions are HTTP Requests GET, HEAD, PUT, POST, DELETE the renao API
    78. 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. 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. 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. 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. 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. 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. 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. 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. 86. future API plans the renao API
    87. 87. future API plans the renao API accept data in more formats
    88. 88. future API plans the renao API accept data in more formats use headers to determine default response format
    89. 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. 90. 1: accept data in more formats the renao API: future plans Check the content-type header on requests and parse body appropriately.
    91. 91. 1: accept data in more formats the renao API: future plans <ul><li>Check the content-type header on requests and parse body appropriately. At least support: </li></ul><ul><ul><li>application/x-www-form-urlencoded </li></ul></ul><ul><ul><li>multipart/form-data </li></ul></ul><ul><ul><li>application/json </li></ul></ul><ul><ul><li>text/xml </li></ul></ul>
    92. 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. 93. 3: device/screen-size detection the renao API: future plans
    94. 94. 3: device/screen-size detection the renao API: future plans All devices use the same urls and domains
    95. 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. 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. 97. a presentation in 3 acts what is renao? the renao API building a community
    98. 98. act 3 building a community
    99. 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. 100. why build a community? building a community
    101. 101. why build a community? power users (designers and developers) can amplify and spread your work building a community
    102. 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. 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. 104. “ create more value than you capture” - Tim O’Reilly building a community
    105. 105. how to attract a community? some ideas building a community
    106. 106. how to attract a community? some ideas provide an online venue for the community to gather building a community
    107. 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. 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. 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. 110. features for power users ideas for designers building a community
    111. 111. features for power users ideas for designers allow for complete design flexibility building a community
    112. 112. features for power users ideas for designers allow for complete design flexibility user-contributed themes gallery building a community
    113. 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. 114. features for power users ideas for developers building a community
    115. 115. features for power users ideas for developers an API that is easy to understand and write for building a community
    116. 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. 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. 118. a presentation in 3 acts what is renao? the renao API building a community fin.
    119. 119. Thanks http://myrenao.com [email_address]
    120. 120. discussion: how do you attract a community around a service? http://myrenao.com [email_address]

    ×