a rest api for content management

A REST API for Content Management

baking semantic web access into

non-geek services

Stephen HowardAthens, Georgia

stephen@enterity.com

http://enterity.com

a presentation in 3 acts

what is renao?

what is renao?the renao API

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?

design managementwhat is renao?

flexible resultswhat is renao?

three guiding principles

what is renao?

content has structure

what is renao?

content has structure URLs are nouns

what is renao?

content has structure URLs are nouns

templates for many formats

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

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

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

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

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:

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

/resource.html

what collection is the resource in?check for template /blog/article.htmlotherwise use /article.html

/resource.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

what is renao?

the renao APIbuilding a community

act 2the renao API

API objectivesthe renao API

access your own site

access your own sitewrite software for others to use

your site is your API, no special urls

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

single authentication scheme

1: access your own sitethe renao API: objectives

update your site to reflect activities around the web

update your site to reflect activities around the webupdate other sites and services to reflect changes on your site

update your site to reflect activities around the webupdate other sites and services to reflect changes on your siteintegrate with your own software projects

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

integrate Renao into existing software

integrate Renao into existing softwarecreate convenience tools

bookmarklets

bookmarkletsbrowser plugins

bookmarkletsbrowser pluginsdesktop apps

integrate Renao into existing software create convenience tools

bookmarkletsbrowser pluginsdesktop apps

start a business

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

provide alternative interfaces for site owners

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

image editors

image editorssyntax highlighters

provide alternative interfaces for site owners desktop apps for richer design file editing

image editorssyntax highlightersfile upload progress indicators

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

Caveatmanaging design files will probably violate the “no

special urls” API rule.

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

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

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

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

GET, HEAD, PUT, POST, DELETE

the renao API

act on the URLs on your site

the renao API

act on the URLs on your siteOAuth for tasks that require authorization

the renao API

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)

// 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)

[% # 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)

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)

# 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

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

http://example.com/about_us

3: device/screen-size detection

All devices use the same urls and domains

All devices use the same urls and domainsUse HTTP User-Agent header to look up templates particular for the device or class of device

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

what is renao?the renao API

building a community

act 3building a community

examples

flickr desktop photo app integrationweb mashupsextended services (printing)

twitter web appsdesktop clients

Wordpress themesplugins

Google Maps mashups

why build 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

“create more value than you capture”

- Tim O’Reilly

how to attract a community?

some ideas

provide an online venue for the community to gather

some ideas

provide an online venue for the community to gathercultivate an atmosphere of helpfulness among service users

some ideas

provide an online venue for the community to gathercultivate an atmosphere of helpfulness among service usersaffiliate program

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

features for power usersideas for designers

allow for complete design flexibility

allow for complete design flexibilityuser-contributed themes gallery

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

features for power usersideas for developers

an API that is easy to understand and write for

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

an API that is easy to understand and write forgood API documentationlow barriers to getting started

what is renao?the renao APIbuilding a community

Thanks

http://myrenao.com

stephen@enterity.com

discussion: how do you attract a community

around a service?

http://myrenao.comstephen@enterity.com

a rest api for content management

text search

single authentication

parse body

password user

power users

template blogarticle

legged provide

parent resource

Technology

force.com rest api developer guide 1 introducing force.com...

microsoft rest api guidelines microsoft rest api ...the...

pro rest api development · pro rest api development with...

salestaxpal - rest api · directly from your applications...

arquitectura api rest

vplex rest api - dell · vplex rest api release 6.2 version...

test driven...

connecting content silos: one cms, many sites with the...

practical rest api

rest api getting started guide -...

csv-w02 open security controller - security orchestration...

[ms-cprest]: control plane rest api... · 2020-03-05 ·...

integrating and extending oracle content and...

wordpress rest api

api deep dive: apic em rest api

api apex rest

docs rest api

unisphere management rest api reference guide · unisphere...

sfdc rest api

rest api security