1 of 44

Describing the Possible with ALPS

Mike Amundsen�@mamund

2 of 44

Overview

A Brief History of Web IDLs
What-if?
How?

3 of 44

A Brief History of Web Interface Description Languages (IDLs)

How far does this go back?

2001

How many do we currently have?

a dozen so far!

4 of 44

WSDL (2001)

Web Service Definition Language
Specific to SOAP Services

5 of 44

AtomSvc

Atom Service Document (2007)
Specific to Atom format/services

6 of 44

WADL (2009)

Web Application Description Language
For "HTTP-based" Services

7 of 44

Swagger (2009)

Swagger is a JSON format from Wordnik
Support both machine and human descriptions

8 of 44

RESTDesc (2010)

Semantic descriptions for Hypermedia APIs
Based on RDF

9 of 44

ioDocs (201?)

Runtime description/managment
JSON format

10 of 44

API Blueprint (2012?)

Describe API and stand up proxy
based on MarkDown

11 of 44

Google Discovery Document (2012)

The Discovery Document describes the surface for a particular version of an API.

12 of 44

JSON Home (2013)

A Discovery format
Based on JSON

13 of 44

JSON Hyperschema (2013)

Based on JSON Schema and JSON Path
Primarily a design-time description

14 of 44

RSDL (2013)

RESTful Service Description Language
Resource-oriented descriptions

15 of 44

RAML (2013)

RESTful API Modeling Language
"It's a way of describing practically-RESTful APIs in a way that's highly readable by both humans and computers."

16 of 44

A Brief History of Web IDLs

Why so many?
Are we missing something?
Is there another way to do this?

17 of 44

They all do the same basic thing

Describe a single instance
of a single server
for a single service

18 of 44

They all do the same basic thing

Is that what we want?
Is that what we need?

19 of 44

What-if...

We could describe a class of services, not just an instance?
We could describe the service independent of media type?
We could describe the service independent of protocol (HTTP, XMPP, CoAP, etc.)
We could describe the service without describing the workflow?

20 of 44

What-If..

We could describe affordances instead of resources?
We could define vocabularies instead of object trees?

What would be possible then?

21 of 44

We could..

Allow implementers to select their preferred media type(s)
Allow implementers to select their preferred protocol(s)
Allow implementers to establish their own workflow�

22 of 44

We could...

Allow servers to own their own URL space
Allow clients to focus on the hypermedia and not the URL

23 of 44

We could...

Focus on a shared vocabulary on the outside without modifying our storage, logical, or business model on the inside.

And clients and servers can still inter-operate.

24 of 44

Wait, has anyone tried this?

XMDP (200?)
Uses microformat vocabularies & HTML

25 of 44

DCAP (2009)

Dublin Core Application Profiles
Uses DC terms and custom text format

26 of 44

And I think we can do even better...

29 of 44

How does it work?

ALPS documents describe:

transitions (hypermedia) and
vocabularies (arguments/data)

Without constraining the:

media type or
protocol

Without dictating the:

URLs or
workflow

30 of 44

Let's do a walk through...

I have searchable "people" store I want to expose via HTTP
I look into the ALPS Repository and find the "Contacts" Profile.
I first pull down the profile...

32 of 44

But...

My data id values don't match the ALPS values….

34 of 44

That's OK...

I can leave my storage name the same and just represent them at runtime using the profile names.
In fact, I'll use Collection+JSON to represent the data and it looks like this...

36 of 44

And I can honor the hypermedia, too

I'll just convert the ALPS safe transition into a Cj query element...

38 of 44

Using Cj means i code two things...

Map my data...

39 of 44