Top Banner
A REST API for Content Management baking semantic web access into non-geek services
120

A REST API for Content Management

Sep 01, 2014

Download

Technology

howars

Baking semantic web access into non-geek services
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Page 1: A REST API for Content Management

A REST API for Content Management

baking semantic web access into

non-geek services

Page 2: A REST API for Content Management

Stephen HowardAthens, Georgia

[email protected]

http://enterity.com

Page 3: A REST API for Content Management

a presentation in 3 acts

Page 4: A REST API for Content Management

a presentation in 3 acts

what is renao?

Page 5: A REST API for Content Management

a presentation in 3 acts

what is renao?the renao API

Page 6: A REST API for Content Management

a presentation in 3 acts

what is renao?the renao APIbuilding a community

Page 7: A REST API for Content Management

act 1what is renao?

Page 8: A REST API for Content Management

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

Page 9: A REST API for Content Management

A hosted content management service

http://myrenao.com

renao [ren-ah-oh], n.

Page 10: A REST API for Content Management

content managementwhat is renao?

Page 11: A REST API for Content Management

content managementwhat is renao?

Page 12: A REST API for Content Management

design managementwhat is renao?

Page 13: A REST API for Content Management

design managementwhat is renao?

Page 14: A REST API for Content Management

flexible resultswhat is renao?

Page 15: A REST API for Content Management

three guiding principles

what is renao?

Page 16: A REST API for Content Management

three guiding principles

what is renao?

content has structure

Page 17: A REST API for Content Management

three guiding principles

what is renao?

content has structure URLs are nouns

Page 18: A REST API for Content Management

three guiding principles

what is renao?

content has structure URLs are nouns

templates for many formats

Page 19: A REST API for Content Management

1: content has structurewhat is renao: 3 guiding principles

Page 20: A REST API for Content Management

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

Page 21: A REST API for Content Management

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

Page 22: A REST API for Content Management

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

Page 23: A REST API for Content Management

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.

Page 24: A REST API for Content Management

2: URLs are nounswhat is renao: 3 guiding principles

Page 25: A REST API for Content Management

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

Page 26: A REST API for Content Management

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

Page 27: A REST API for Content Management

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

Page 28: A REST API for Content Management

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

Page 29: A REST API for Content Management

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

Page 30: A REST API for Content Management

3: templates for many formats

what is renao: 3 guiding principles

how renao picks from your templates for a given request:

Page 31: A REST API for Content Management

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:

Page 32: A REST API for Content Management

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:

Page 33: A REST API for Content Management

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:

Page 34: A REST API for Content Management

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:

Page 35: A REST API for Content Management

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:

Page 36: A REST API for Content Management

a presentation in 3 acts

what is renao?

the renao APIbuilding a community

Page 37: A REST API for Content Management

act 2the renao API

Page 38: A REST API for Content Management

API objectivesthe renao API

Page 39: A REST API for Content Management

API objectivesthe renao API

access your own site

Page 40: A REST API for Content Management

API objectivesthe renao API

access your own sitewrite software for others to use

Page 41: A REST API for Content Management

API objectivesthe renao API

access your own sitewrite software for others to use

your site is your API, no special urls

Page 42: A REST API for Content Management

API objectivesthe renao API

access your own sitewrite software for others to use

your site is your API, no special urlsmanage content and design

Page 43: A REST API for Content Management

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

Page 44: A REST API for Content Management

1: access your own sitethe renao API: objectives

Page 45: A REST API for Content Management

1: access your own sitethe renao API: objectives

update your site to reflect activities around the web

Page 46: A REST API for Content Management

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

Page 47: A REST API for Content Management

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

Page 48: A REST API for Content Management

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.

Page 49: A REST API for Content Management

2: write software for others

the renao API: objectives

Page 50: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing software

Page 51: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing softwarecreate convenience tools

Page 52: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing softwarecreate convenience tools

bookmarklets

Page 53: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing softwarecreate convenience tools

bookmarkletsbrowser plugins

Page 54: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing softwarecreate convenience tools

bookmarkletsbrowser pluginsdesktop apps

Page 55: A REST API for Content Management

2: write software for others

the renao API: objectives

integrate Renao into existing software create convenience tools

bookmarkletsbrowser pluginsdesktop apps

start a business

Page 56: A REST API for Content Management

3: your site is your APIthe renao API: objectives

Page 57: A REST API for Content Management

3: your site is your APIthe renao API: objectives

Minimize the amount of extra code to support an API

Page 58: A REST API for Content Management

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

Page 59: A REST API for Content Management

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

Page 60: A REST API for Content Management

4: manage content and design

the renao API: objectives

Page 61: A REST API for Content Management

4: manage content and design

the renao API: objectives

provide alternative interfaces for site owners

Page 62: A REST API for Content Management

4: manage content and design

the renao API: objectives

provide alternative interfaces for site ownersdesktop apps for richer design file editing

Page 63: A REST API for Content Management

4: manage content and design

the renao API: objectives

provide alternative interfaces for site ownersdesktop apps for richer design file editing

image editors

Page 64: A REST API for Content Management

4: manage content and design

the renao API: objectives

provide alternative interfaces for site ownersdesktop apps for richer design file editing

image editorssyntax highlighters

Page 65: A REST API for Content Management

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

Page 66: A REST API for Content Management

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

Page 67: A REST API for Content Management

4: manage content and design

the renao API: objectives

Caveatmanaging design files will probably violate the “no

special urls” API rule.

Page 68: A REST API for Content Management

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

Page 69: A REST API for Content Management

5: single authentication scheme

the renao API: objectives

Page 70: A REST API for Content Management

5: single authentication scheme

the renao API: objectives

OAuth

Page 71: A REST API for Content Management

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

Page 72: A REST API for Content Management

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

Page 73: A REST API for Content Management

single authentication scheme

the renao API: objectives

QuickTime™ and a decompressor

are needed to see this picture.

http://oauth.net/core/1.0

Page 74: A REST API for Content Management

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

Page 75: A REST API for Content Management

using the renao API

the renao API

Page 76: A REST API for Content Management

using the renao APIactions are HTTP Requests

the renao API

Page 77: A REST API for Content Management

using the renao APIactions are HTTP Requests

GET, HEAD, PUT, POST, DELETE

the renao API

Page 78: A REST API for Content Management

using the renao APIactions are HTTP Requests

GET, HEAD, PUT, POST, DELETE

act on the URLs on your site

the renao API

Page 79: A REST API for Content Management

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

Page 80: A REST API for Content Management

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

Page 81: A REST API for Content Management

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)

Page 82: A REST API for Content Management

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)

Page 83: A REST API for Content Management

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)

Page 84: A REST API for Content Management

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)

Page 85: A REST API for Content Management

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)

Page 86: A REST API for Content Management

future API plans

the renao API

Page 87: A REST API for Content Management

future API plans

the renao API

accept data in more formats

Page 88: A REST API for Content Management

future API plans

the renao API

accept data in more formatsuse headers to determine default response format

Page 89: A REST API for Content Management

future API plans

the renao API

accept data in more formatsuse headers to determine default response formatadd device/screen-size detection for template selection

Page 90: A REST API for Content Management

1: accept data in more formats

the renao API: future plans

Check the content-type header on requests and parse body appropriately.

Page 91: A REST API for Content Management

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

Page 92: A REST API for Content Management

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

Page 93: A REST API for Content Management

3: device/screen-size detection

the renao API: future plans

Page 94: A REST API for Content Management

3: device/screen-size detection

the renao API: future plans

All devices use the same urls and domains

Page 95: A REST API for Content Management

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

Page 96: A REST API for Content Management

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

Page 97: A REST API for Content Management

a presentation in 3 acts

what is renao?the renao API

building a community

Page 98: A REST API for Content Management

act 3building a community

Page 99: A REST API for Content Management

examples

building a community

flickr desktop photo app integrationweb mashupsextended services (printing)

twitter web appsdesktop clients

Wordpress themesplugins

Google Maps mashups

Page 100: A REST API for Content Management

why build a community?

building a community

Page 101: A REST API for Content Management

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

building a community

Page 102: A REST API for Content Management

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

Page 103: A REST API for Content Management

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

Page 104: A REST API for Content Management

“create more value than you capture”

- Tim O’Reilly

building a community

Page 105: A REST API for Content Management

how to attract a community?

some ideas

building a community

Page 106: A REST API for Content Management

how to attract a community?

some ideas

provide an online venue for the community to gather

building a community

Page 107: A REST API for Content Management

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

Page 108: A REST API for Content Management

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

Page 109: A REST API for Content Management

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

Page 110: A REST API for Content Management

features for power usersideas for designers

building a community

Page 111: A REST API for Content Management

features for power usersideas for designers

allow for complete design flexibility

building a community

Page 112: A REST API for Content Management

features for power usersideas for designers

allow for complete design flexibilityuser-contributed themes gallery

building a community

Page 113: A REST API for Content Management

features for power usersideas for designers

allow for complete design flexibilityuser-contributed themes galleryfree “project starter” sites for new client sites

building a community

Page 114: A REST API for Content Management

features for power usersideas for developers

building a community

Page 115: A REST API for Content Management

features for power usersideas for developers

an API that is easy to understand and write for

building a community

Page 116: A REST API for Content Management

features for power usersideas for developers

an API that is easy to understand and write forgood API documentation

building a community

Page 117: A REST API for Content Management

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

Page 118: A REST API for Content Management

a presentation in 3 acts

what is renao?the renao APIbuilding a community

fin.

Page 119: A REST API for Content Management

Thanks

http://myrenao.com

[email protected]

Page 120: A REST API for Content Management

discussion: how do you attract a community

around a service?

http://[email protected]