AtomPub, beyond blogs Using the AtomPub protocol as the base of your Web API

Questions for you

• Are you familiar with HTTP (Methods, Status codes etc) ?

• Are you familiar with Web Services/APIs?

• Are you familiar with AtomPub?

• Have you developed a web service before ?

• Have you used/written WS-* ?

• Have used/written AtomPub ?

Your mission - Build a web service that:

• Speaks HTTP, across the Internet

• Is scalable and robust

• Caters to heterogeneous clients (browsers, terminals, other web services )

•Language neutral (Java,PHP,Perl,Python, Ruby and god forbid C , C++ ;))

Options ?(Architecture - wise)

RPC Architecture

• Uses HTTP as a transport protocol - not an application protocol

• Maps procedural programming model to the Web - parameters and method calls are serialized

• Problems already solved by HTTP need to be handled (error handling, caching etc.)

• E.g. XML-RPC and ...

WS - *

"The SOAP stack is generally regarded as an

embarrassing failure these days" Tim Bray

http://www.infoworld.com/article/08/07/24/Sun-technologist-SOAP-stack-a-failure_1.html

RESTful architecture

• HTTP used correctly- application protocol

• Everything has an ID (Link-able)

• Everything is linked to each other

• Fixed interface(GET,PUT,POST,DELETE,HEAD,OPTIONS)

• Multiple representations of a resource

• Stateless

What does using HTTP as an

application protocol give you

for free ?

HTTP Pipelining

Compression (Transport encoding)

Caching (Last-modified, If-modified-since, E-tags,Cache controls)

Content negotiation (mimetype/content type)

Error handling (HTTP status codes)

Simple tooling (curl anybody ?)

Concurrency handling (Optimistic concurrency - If-Match)

Layered approach (Atompub + Opensearch + Digest authentication)

• Atom is both a format and a protocol

• A way to use HTTP correctly

AtomPub is a REST styled protocol (RESTful)

Services using AtomPub

• Google: GData

• Microsoft: Live Platform, Astoria

• IBM: Lotus Connector

• LCA: Resource synchronisation :-)

AtomPub 101

AtomPub 101The data model

Entry

Defines the essential pieces of a document

Essential pieces

• Title

• Author(s)

• ID

• Published Date

• Content

Feed

This is the envelope for entries

Service document

An introspection document for collections

AtomPub 101Operations

Operations on CollectionsMethod Resource Representation Description

GET Collection Atom Feed Retrieve a list of members

POST Collection Atom Entry Add a new member

Operations on MembersMethod Resource Representation Description

GET Member Atom Entry Retrieve a member representation

PUT Member Atom Entry Update a member representation

DELETE Member n/a Delete a member

POST to a collection to create an entry(Request)

POST to a collection to create an entry(Response)

Result

PUT to edit URL to update

GET the entry URL to update

PUT to edit URL to update (Retrieve)

PUT to edit URL to update (Request)

DELETE to edit URL to delete (Request)

When is AtomPub suitable for you ?

Dealing with collections of documents / resources

The collection-item metaphor is a powerful abstraction

Time indexed resources

Sales orders, members, events, filesystem, articles, relationships, transactions

Operations can be mapped to CRUD + List

• Requires some thinking

• Tough when not time indexed

• Something messaging model is better

Heterogeneous & Interop important

"[I]f you don't have control of both ends of the wire then loosely typed documents beat strongly typed data-structure serializations."

http://bitworking.org/news/Nelson_Minar_on_SOAP

http://bitworking.org/news/125/REST-and-WS

Homogenous systems - Serializing objects work OK

Heterogeneous systems - Move towards self descriptive documents

Misconception

Only good for blogs, html/xml type data

Your content in AtomPub

Re-orientate your thinking

• Move from a service orientation to a resource orientation (‘verb to noun’)

• Identify the resources in your system - ‘nouns’

• Map them into collections and entries

• Map the standard interface to the required operations

First identify the entry mandatory fields

In content element

In content element

• Leverage mimetypes -text, html, xhtml

• Use microformats

• Custom XML - Use - application/xml

Extending with custom name space

Use media link entries

Mapping operations

• Google Finance a great example

• Operations mapped

• Managing portfolios

• Managing positions

• Managing transactions

http://code.google.com/apis/finance/developers_guide_protocol.html

What you get ?Standard API

Pagination (RFC 5005)

Discovery (Service document)

Categorization (Atom:category)

Simple sync ( using app:edited )

Test suites for client and servers (Very IMPORTANT! - APE, feedvalidator, JGs apptestclient)

Existing implementations (client and server) that interop (http://intertwingly.net/wiki/pie/InteropGrid)

Existing libraries and toolkits

Limitations ?Multi-depth hierarchies (Possible by such things as rel attrib)

Incremental updates of entries (HTTP Patch, XML Diff)

Multiple(Batch) operations (Being sorted with multipart extension)

Querying (Open search)

Synchronisation (Feed sync , simple system of timestamps)

Long running transactions (Break down the collections)

Collection creation and handling (MetaAtompub)

Authentication / Encryption (Use existing auth schemes)

AtomPub as a layer in the stack

• Consume• curl• httplib2 (any httplib)

• Produce• Amplee (Library) - Python• php-atompub-server - PHP• Abdera(Library) - Java• Catalyst::Controller::Atompub -Perl• mod_atom - C/Apache

Toolkits

mohangk@gmail.commohangk.org/blog