ALPS sample implementation - rest

Question

I'm looking for a sample client implementation utilizing ALPS (not the mountains but the Application-Level Profile Semantics).
Do YOU! have one?
I've looked into the related RFC draft and discussions but still can figure it quite out.
Specifically I would like to know how my client should know what the descriptor describes, given that my client supposedly knows nothing about the structure and semantics of the REST API as the REST principle demands?
As a human I know that a descriptor with an id tag called "users" is likely to describe how to interact with users but how is my client to know without me telling him explicitly?
I know I could insert some kind of keyword to show up in the descriptor and tell my client to match the appropriate ones but this seems hardly the right way.
I happily provide a more detailed example given somebody is willing to read it.

Answer 1

I'm exploring ALPS for the first time too, and my understanding from that RFC draft wasn't immediate either.
Here is a slideshow (166 slides, so it's not possible to copy it all into this answer) from the author of the RFC which I think gives a much better understanding of the role ALPS plays.
As a human I know that a descriptor with an id tag called users is likely to describe how to interact with users but how is my client to know this without me telling him explicitly?
From this slideshow, I deduce this answer to your question: He doesn't.
In the slideshow, a sample ALPS profile is compared with equivalent HTML code for a form submit. The browser knows how to render the HTML to the screen, but only the human knows what it means to POST that form with those input fields, using that submit button.
Here is an example Complete JSON Representation taken from alps.io
{
"alps" : {
"version" : "1.0",
"doc" : {
"href" : "http://example.org/samples/full/doc.html"
},
"descriptor" : [
{
"id" : "search",
"type" : "safe",
"doc" : {"value" :
"A search form with a two inputs"
},
"descriptor" : [
{
"id" : "value",
"name" : "search",
"type" : "descriptor",
"doc" : { "value" : "input for search" }
},
{ "href" : "#resultType" }
]
},
{
"id" : "resultType",
"type" : "descriptor",
"description" : {"value" : "results format"},
"ext" : [
{
"href" : "http://alps.io/ext/range",
"value" : "summary,detail"
}
]
}
]
}
}
Take, for example, a generic mobile phone app which is displaying screens to the user based on REST responses. Say a HAL+Json response contains a reference to a search entity. The app can lookup in this ALPS document what a search entity is, and can be coded on how to represent that. Namely, a search is something which has a name/value pair (with an id) and a href. The href refers to the second descriptor with id resultType which lets the app know the format to expect for search results. The actual URLs and data involved would come from the REST responses.
From July 2014, here is a Spring blog article describing the ALPS for an app which manages a "To Do List". The ALPS document describes
What is a todo entity
What actions can be done with a todo entity
An abridged version of the ALPS profile for that small app:
{
"version" : "1.0",
"descriptors" : [ {
"id" : "todo-representation",
"descriptors" : [ {
"name" : "description",
"doc" : {
"value" : "Details about the TODO item",
"format" : "TEXT"
},
"type" : "SEMANTIC"
}, {
"name" : "title",
"doc" : {
"value" : "Title for the TODO item",
"format" : "TEXT"
},
"type" : "SEMANTIC"
}, {
"name" : "id",
"type" : "SEMANTIC"
}, {
"name" : "completed",
"doc" : {
"value" : "Is it completed?",
"format" : "TEXT"
},
"type" : "SEMANTIC"
} ]
}, {
"id" : "create-todos",
"name" : "todos",
"type" : "UNSAFE",
"rt" : "#todo-representation"
}, {
"id" : "get-todos",
"name" : "todos",
"type" : "SAFE",
"rt" : "#todo-representation"
}, {
"id" : "delete-todo",
"name" : "todo",
"type" : "IDEMPOTENT",
"rt" : "#todo-representation"
} ]
}
I guess one way to think of it might as a kind "schema", but instead of database tables, it's describing the scope of REST responses.