[Geoserver-devel] more rest configuration api feedback, discovery

GeoServer GeoServer Developer
1

Hi all,

Last week i sent the current rest configuration api to the geo-web-rest group and got some good feedback. Here is the thread:

http://groups.google.com/group/geo-web-rest/browse_thread/thread/bbc91cfa9314d870

I have some ideas on how to proceed but wanted to bounce off the list for additional feedback.

The first has to do with "discovery". Currently the way the api is structured it relies on a lot of pre-existing knowledge built into the client. Which actually makes it non-RESTful. Instead, as enlightened by Sean, the workflow should be hypertext driven, where a client should be able to request a "discovery" document, and determine the uri structure dynamically, drilling down so to speak.

Sean also pointed me at the scheme used by opensocial:

http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol

(See section 5, discovery).

Basically they have adopted a URI-template scheme which describes the URI's available to the client in an xml document. I think this method makes a lot sense, and naturally fits into our implementation.

Currently, our "discovery mechanism" so to speak is the IndexRestlet that David describes in a previous email:

"The longer, but more technically accurate answer is that it does expose
one endpoint; that being an index page which lists all non-parameterized
REST pages. The idea is that you can find out what services are
provided and, if the developers have made the effort to keep them
HTML-friendly, navigate them through the browser."

The idea of a formal discovery document takes this a step further.

Thoughts? Opinions? Ideas?

-Justin

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

2

Justin Deoliveira ha scritto:
...

"The longer, but more technically accurate answer is that it does expose
one endpoint; that being an index page which lists all non-parameterized
REST pages. The idea is that you can find out what services are
provided and, if the developers have made the effort to keep them
HTML-friendly, navigate them through the browser."

The idea of a formal discovery document takes this a step further.

Thoughts? Opinions? Ideas?

Hum hum, the xml document looks fine, but what if we have some query
parameters that a resource can answer to?
I'm thinking about URL that do expose algorithms (sometimes called
"algorithmic resources"), such as the map classification ones
exposed by sldService (thematic mapping with quantile classification
and the like)?

Finally, what do we do if for practical reasons it's not possible
to use GET because the params are just too many (and thus we use
POST instead), how do we describe that?
I know that one answer would be to PUT the
params somewhere on the server, but that would make the
conversation stateful, requiring either sessions and session
local storage, or actual server wise storage and some cleanup
mechanism to get rid of these params when we're done with them.

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

3

Andrea Aime wrote:

Justin Deoliveira ha scritto:
...

"The longer, but more technically accurate answer is that it does expose
one endpoint; that being an index page which lists all non-parameterized
REST pages. The idea is that you can find out what services are
provided and, if the developers have made the effort to keep them
HTML-friendly, navigate them through the browser."

The idea of a formal discovery document takes this a step further.

Thoughts? Opinions? Ideas?

Hum hum, the xml document looks fine, but what if we have some query
parameters that a resource can answer to?
I'm thinking about URL that do expose algorithms (sometimes called
"algorithmic resources"), such as the map classification ones
exposed by sldService (thematic mapping with quantile classification
and the like)?

I think that still works... the URI-template scheme is defined more formally here:

http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html

And does support query string parameters. Was that the concern?

Finally, what do we do if for practical reasons it's not possible
to use GET because the params are just too many (and thus we use
POST instead), how do we describe that?
I know that one answer would be to PUT the
params somewhere on the server, but that would make the
conversation stateful, requiring either sessions and session
local storage, or actual server wise storage and some cleanup
mechanism to get rid of these params when we're done with them.

Yeah... as far as I know using POST to query is not the RESTful way. The PUT then GET approach I have heard about as well. As for how to describe that in a discovery document, you have got me. I guess this is knowledge that has to be built-in to the client... tough to say.

Cheers
Andrea

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

4

Justin Deoliveira ha scritto:

Andrea Aime wrote:

Justin Deoliveira ha scritto:
...

"The longer, but more technically accurate answer is that it does expose
one endpoint; that being an index page which lists all non-parameterized
REST pages. The idea is that you can find out what services are
provided and, if the developers have made the effort to keep them
HTML-friendly, navigate them through the browser."

The idea of a formal discovery document takes this a step further.

Thoughts? Opinions? Ideas?

Hum hum, the xml document looks fine, but what if we have some query
parameters that a resource can answer to?
I'm thinking about URL that do expose algorithms (sometimes called
"algorithmic resources"), such as the map classification ones
exposed by sldService (thematic mapping with quantile classification
and the like)?

I think that still works... the URI-template scheme is defined more formally here:

http://bitworking.org/projects/URI-Templates/spec/draft-gregorio-uritemplate-03.html

And does support query string parameters. Was that the concern?

Yep.

Finally, what do we do if for practical reasons it's not possible
to use GET because the params are just too many (and thus we use
POST instead), how do we describe that?
I know that one answer would be to PUT the
params somewhere on the server, but that would make the
conversation stateful, requiring either sessions and session
local storage, or actual server wise storage and some cleanup
mechanism to get rid of these params when we're done with them.

Yeah... as far as I know using POST to query is not the RESTful way. The PUT then GET approach I have heard about as well. As for how to describe that in a discovery document, you have got me. I guess this is knowledge that has to be built-in to the client... tough to say.

Eh, the clean model and the reality don't always match. If we want to
get clean, we need to add support for those fake, temporary resources
used just to communicate with the server in a purely restful way :frowning:

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.