A REST API for Content Management baking semantic web access into non-geek services
Sep 01, 2014
A REST API for Content Management
baking semantic web access into
non-geek services
a presentation in 3 acts
a presentation in 3 acts
what is renao?
a presentation in 3 acts
what is renao?the renao API
a presentation in 3 acts
what is renao?the renao APIbuilding a community
act 1what is renao?
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. Moorehttp://myrenao.com/what
A hosted content management service
http://myrenao.com
renao [ren-ah-oh], n.
content managementwhat is renao?
content managementwhat is renao?
design managementwhat is renao?
design managementwhat is renao?
flexible resultswhat is renao?
three guiding principles
what is renao?
three guiding principles
what is renao?
content has structure
three guiding principles
what is renao?
content has structure URLs are nouns
three guiding principles
what is renao?
content has structure URLs are nouns
templates for many formats
1: content has structurewhat is renao: 3 guiding principles
1: content has structurewhat is renao: 3 guiding principles
most organizations have collections of things (resources), physical or conceptual, that they want to publish online
1: content has structurewhat is renao: 3 guiding principles
most organizations have collections of things (resources), physical or conceptual, that they want to publish onlinethese resources usually have a consistent set of structured or semi-structured information
1: content has structurewhat is renao: 3 guiding principles
most organizations have collections of things (resources), physical or conceptual, that they want to publish onlinethese resources usually have a consistent set of structured or semi-structured informationlet them use these structures they’re already familiar with when adding content to their sites
1: content has structurewhat is renao: 3 guiding principles
most organizations have collections of things (resources), physical or conceptual, that they want to publish onlinethese resources usually have a consistent set of structured or semi-structured informationlet them use these structures they’re already familiar with when adding content to their sitesa better format for machines to understand than flat html pages.
2: URLs are nounswhat is renao: 3 guiding principles
2: URLs are nounswhat is renao: 3 guiding principles
URLs can refer to a specific resourcehttp://example.com/about_ushttp://example.com/blog/designing_an_api
2: URLs are nounswhat is renao: 3 guiding principles
URLs can refer to a specific resourcehttp://example.com/about_ushttp://example.com/blog/designing_an_api
or a list of resourceshttp://example.com/Articles
2: URLs are nounswhat is renao: 3 guiding principles
URLs can refer to a specific resourcehttp://example.com/about_ushttp://example.com/blog/designing_an_api
or a list of resourceshttp://example.com/Articles
use query parameters to refine your results/Articles?name[like]=perl&sort=publish_date,desc
2: URLs are nounswhat is renao: 3 guiding principles
URLs can refer to a specific resourcehttp://example.com/about_ushttp://example.com/blog/designing_an_api
or a list of resourceshttp://example.com/Articles
use query parameters to refine your results/Articles?name[like]=perl&sort=publish_date,desc
or use the full-text search parameter insteadhttp://example.com?q=perlhttp://example.com/blog?q=perl
2: URLs are nounswhat is renao: 3 guiding principles
URLs can refer to a specific resourcehttp://example.com/about_ushttp://example.com/blog/designing_an_api
or a list of resourceshttp://example.com/Articles
use query parameters to refine your results/Articles?name[like]=perl&sort=publish_date,desc
or use the full-text search parameter insteadhttp://example.com?q=perlhttp://example.com/blog?q=perl
special shortcut URLs for tagshttp://example.com/Articles/t/perlhttp://example.com/blog/t/perl
3: templates for many formats
what is renao: 3 guiding principles
how renao picks from your templates for a given request:
3: templates for many formats
what is renao: 3 guiding principles
what kind of resource is it?/article.html
how renao picks from your templates for a given request:
3: templates for many formats
what is renao: 3 guiding principles
what kind of resource is it?/article.html
can’t find a template for that resource type?look for a template for the parent resource type.
/resource.html
how renao picks from your templates for a given request:
3: templates for many formats
what is renao: 3 guiding principles
what kind of resource is it?/article.html
can’t find a template for that resource type?look for a template for the parent resource type.
/resource.html
is the request for a list of resources?/articles.html
how renao picks from your templates for a given request:
3: templates for many formats
what is renao: 3 guiding principles
what kind of resource is it?/article.html
can’t find a template for that resource type?look for a template for the parent resource type.
/resource.html
is the request for a list of resources?/articles.html
what collection is the resource in?check for template /blog/article.htmlotherwise use /article.html
how renao picks from your templates for a given request:
3: templates for many formats
what is renao: 3 guiding principles
what kind of resource is it?/article.html
can’t find a template for that resource type?look for a template for the parent resource type.
/resource.html
is the request for a list of resources?/articles.html
what collection is the resource in?check for template /blog/article.htmlotherwise use /article.html
is there a specific extension on the url?ends in .xml? -> use /article.xml
how renao picks from your templates for a given request:
a presentation in 3 acts
what is renao?
the renao APIbuilding a community
act 2the renao API
API objectivesthe renao API
API objectivesthe renao API
access your own site
API objectivesthe renao API
access your own sitewrite software for others to use
API objectivesthe renao API
access your own sitewrite software for others to use
your site is your API, no special urls
API objectivesthe renao API
access your own sitewrite software for others to use
your site is your API, no special urlsmanage content and design
API objectivesthe renao API
access your own sitewrite software for others to use
your site is your API, no special urlsmanage content and design
single authentication scheme
1: access your own sitethe renao API: objectives
1: access your own sitethe renao API: objectives
update your site to reflect activities around the web
1: access your own sitethe renao API: objectives
update your site to reflect activities around the webupdate other sites and services to reflect changes on your site
1: access your own sitethe renao API: objectives
update your site to reflect activities around the webupdate other sites and services to reflect changes on your siteintegrate with your own software projects
1: access your own sitethe renao API: objectives
update your site to reflect activities around the webupdate other sites and services to reflect changes on your siteintegrate with your own software projectstools and shortcuts that better match how you work.
2: write software for others
the renao API: objectives
2: write software for others
the renao API: objectives
integrate Renao into existing software
2: write software for others
the renao API: objectives
integrate Renao into existing softwarecreate convenience tools
2: write software for others
the renao API: objectives
integrate Renao into existing softwarecreate convenience tools
bookmarklets
2: write software for others
the renao API: objectives
integrate Renao into existing softwarecreate convenience tools
bookmarkletsbrowser plugins
2: write software for others
the renao API: objectives
integrate Renao into existing softwarecreate convenience tools
bookmarkletsbrowser pluginsdesktop apps
2: write software for others
the renao API: objectives
integrate Renao into existing software create convenience tools
bookmarkletsbrowser pluginsdesktop apps
start a business
3: your site is your APIthe renao API: objectives
3: your site is your APIthe renao API: objectives
Minimize the amount of extra code to support an API
3: your site is your APIthe renao API: objectives
Minimize the amount of extra code to support an API
Minimize the number of API-specific urls
3: your site is your APIthe 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
4: manage content and design
the renao API: objectives
4: manage content and design
the renao API: objectives
provide alternative interfaces for site owners
4: manage content and design
the renao API: objectives
provide alternative interfaces for site ownersdesktop apps for richer design file editing
4: manage content and design
the renao API: objectives
provide alternative interfaces for site ownersdesktop apps for richer design file editing
image editors
4: manage content and design
the renao API: objectives
provide alternative interfaces for site ownersdesktop apps for richer design file editing
image editorssyntax highlighters
4: manage content and design
the renao API: objectives
provide alternative interfaces for site owners desktop apps for richer design file editing
image editorssyntax highlightersfile upload progress indicators
4: manage content and design
the renao API: objectives
provide alternative interfaces for site owners desktop apps for richer design file editing
image editorssyntax highlightersfile upload progress indicators
implement features I wouldn’t think of, don’t have time for, or don’t want
4: manage content and design
the renao API: objectives
Caveatmanaging design files will probably violate the “no
special urls” API rule.
4: manage content and design
the renao API: objectives
Caveatmanaging design files will probably violate the “no
special urls” API rule.
normal graphics, scripts and css directories should be:fast:
no permission checksminimal server side scripting
potentially:distributable across a CDN
5: single authentication scheme
the renao API: objectives
5: single authentication scheme
the renao API: objectives
OAuth
5: single authentication scheme
the renao API: objectives
OAuth
3-leggedprovide access on behalf of another usernever have to ask for or store the user’s username and passwordUser grants you an access-token which they have the power to revoke at a later date
5: single authentication scheme
the renao API: objectives
OAuth
2-leggedskip access-token dancesend token-less OAuth requests for resources on your own sites
3-leggedprovide access on behalf of another usernever have to ask for or store the user’s username and passwordUser grants you an access-token which they have the power to revoke at a later date
single authentication scheme
the renao API: objectives
QuickTime™ and a decompressor
are needed to see this picture.
http://oauth.net/core/1.0
integrating the API
the renao API
apache request cycle
for all requests
for API compatibility
PerlInitHandler map domain to site and account
request_method browser fix-up
PerlTransHandler map url to resource(s)
PerlAccessHandler initialize session cookies or OAuth?
PerlResponseHandler the main event code written with REST in mind
PerlLogHandler logging
PerlCleanupHandler session cleanup
using the renao API
the renao API
using the renao APIactions are HTTP Requests
the renao API
using the renao APIactions are HTTP Requests
GET, HEAD, PUT, POST, DELETE
the renao API
using the renao APIactions are HTTP Requests
GET, HEAD, PUT, POST, DELETE
act on the URLs on your site
the renao API
using the renao APIactions are HTTP Requests
GET, HEAD, PUT, POST, DELETE
act on the URLs on your siteOAuth for tasks that require authorization
the renao API
using the renao APIactions are HTTP Requests
GET, HEAD, PUT, POST, DELETE
act on the URLs on your siteOAuth for tasks that require authorization
account with developer key and passcode
the renao API
sometimes you can get stuff done without authenticating
the renao API: examples
<h3> <a href="http://myrenao.com/discuss" class="recent_topics"> Recent Community Discussion Topics </a> <img src="/graphics/icons/go.png" alt="go" /></h3><h3> <a href=" http://enterity.myrenao.com/blog " class="recent_topics"> Recent Blog Posts </a> <img src="/graphics/icons/go.png" alt="go" /></h3>
(1 of 3)
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("(http://[^/]+)"); 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="'+baseurl+resources[i].uri+'">'+name+'</a></h4>’ ); } })}
// hook into the html -----------------
$(function(){ $('a.recent_topics').each(function(){ Widget.RecentTopics(this); });});
(2 of 3)
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)
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;
using Perl and Net::OAuth(1 of 2)
the renao API: examples
# make HTTP Request -----------------
my $response = LWP::UserAgent->new->request(
POST "http://$site$url",
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 ? "successfully posted to site\n" : "something went wrong\n”;
print $response->status_line . "\n” . $response->decoded_content . "\n";
using Perl and Net::OAuth(2 of 2)
future API plans
the renao API
future API plans
the renao API
accept data in more formats
future API plans
the renao API
accept data in more formatsuse headers to determine default response format
future API plans
the renao API
accept data in more formatsuse headers to determine default response formatadd device/screen-size detection for template selection
1: accept data in more formats
the renao API: future plans
Check the content-type header on requests and parse body appropriately.
1: accept data in more formats
the renao API: future plans
Check the content-type header on requests and parse body appropriately. At least support:
application/x-www-form-urlencodedmultipart/form-dataapplication/jsontext/xml
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
3: device/screen-size detection
the renao API: future plans
3: device/screen-size detection
the renao API: future plans
All devices use the same urls and domains
3: device/screen-size detection
the renao API: future plans
All devices use the same urls and domainsUse HTTP User-Agent header to look up templates particular for the device or class of device
3: device/screen-size detection
the renao API: future plans
All devices use the same urls and domainsUse HTTP User-Agent header to look up templates particular for the device or class of deviceEliminates the need to maintain multiple copies or interfaces to your content for different devices
a presentation in 3 acts
what is renao?the renao API
building a community
act 3building a community
examples
building a community
flickr desktop photo app integrationweb mashupsextended services (printing)
twitter web appsdesktop clients
Wordpress themesplugins
Google Maps mashups
why build a community?
building a community
why build a community?power users (designers and developers) can amplify and spread your work
building a community
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
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
“create more value than you capture”
- Tim O’Reilly
building a community
how to attract a community?
some ideas
building a community
how to attract a community?
some ideas
provide an online venue for the community to gather
building a community
how to attract a community?
some ideas
provide an online venue for the community to gathercultivate an atmosphere of helpfulness among service users
building a community
how to attract a community?
some ideas
provide an online venue for the community to gathercultivate an atmosphere of helpfulness among service usersaffiliate program
building a community
how to attract a community?
some ideas
provide an online venue for the community to gathercultivate an atmosphere of helpfulness among service usersaffiliate programprovide features that will attract power users
building a community
features for power usersideas for designers
building a community
features for power usersideas for designers
allow for complete design flexibility
building a community
features for power usersideas for designers
allow for complete design flexibilityuser-contributed themes gallery
building a community
features for power usersideas for designers
allow for complete design flexibilityuser-contributed themes galleryfree “project starter” sites for new client sites
building a community
features for power usersideas for developers
building a community
features for power usersideas for developers
an API that is easy to understand and write for
building a community
features for power usersideas for developers
an API that is easy to understand and write forgood API documentation
building a community
features for power usersideas for developers
an API that is easy to understand and write forgood API documentationlow barriers to getting started
building a community
a presentation in 3 acts
what is renao?the renao APIbuilding a community
fin.