ALPS sampling implementation
I'm looking for an example client implementation using ALPS (not mountains, but application profile semantics).
YOU! Is there?
I've looked over the associated RFC draft and discussion, but can still figure it out perfectly.
In particular, I would like to know how my client is supposed to 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 requires?
As a person, I know that a tagged descriptor id
called "users" is likely to describe how to interact with users, but how does my client know that I am not telling them explicitly?
I know I could insert some kind of display keyword in the descriptor and tell my client to match the relevant ones, but that hardly seems to fit.
I have happily provided a more detailed example in case anyone wants to read it.
source to share
I am also studying ALPS for the first time, and my understanding from this draft RFC was also not immediate.
Here is a slideshow (166 slides, so there is no way to copy it all in this answer) from the author of the RFC, which I think gives a much better understanding of the role of ALPS.
As a person, I know that
descriptor
a tagid
called by users will most likely describe how to interact with users, but how does my client know if I don't tell him explicitly?
From this slideshow, I find this answer to your question: it doesn't.
The slideshow compares the ALPS sample to the equivalent HTML for the submit form. The browser knows how to display HTML on the screen, but only the human knows what the POST means, which is generated with these input fields using this submit button.
Here is an example Full 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 application that displays screens to the user based on REST responses. Let's say the response HAL+Json
contains a link to a search object. An application can search in this ALPS document for what is being searched for and can be coded about how to represent it. Namely, a search is something that has a pair name/value
(with an id) and href
. href
refers to the second descriptor
, id result, which allows the application to know the format expected of the search results. Actual urls and data will be associated with REST responses.
Since July 2014, here's a Spring blog article describing ALPS for an application that manages "To Do List". The ALPS document describes
- What is a todo object
- What actions can be performed using the todo object.
An abbreviated version of the ALPS profile for this small application:
{
"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"
} ]
}
My guess is that one way to think of this might be as a "schema" rather than database tables describing the scope of the REST responses.
source to share