[Geoserver-devel] Enhancements to the REST API

All,

With the migration to Git and creation of branch 2.2.x done, I’d like to gather feedback on a proposed enhancement to the REST API that I worked on a few weeks ago, which adds configuration options for global settings and OWS services. I wrote a GSIP with the high level description of changes introduced at the following URL:

http://geoserver.org/display/GEOS/GSIP+76±+Extend+REST+API+to+configure+settings+and+OWS+services

The associated patch with unit tests and documentation for these changes is attached in the corresponding JIRA ticket at:

https://jira.codehaus.org/browse/GEOS-5122

Thanks


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com

Hey Juan,

All in all this proposal looks great. Nice work man.

One thing though is about the ServiceInfo object representations. I would expect them to match the representation stored on disk for the data directory. Its understandable why though don’t through since there is a secondary interfaces / set of classes used for this loaded by extension point.

The extension point is XStreamServiceLoader and you’ll find subclasses for each of the ows services. I think we should use this for the xml and json representations of service objects. For an example of how to use the extension point see:

https://github.com/geoserver/geoserver/blob/master/src/main/src/main/java/org/geoserver/config/GeoServerLoader.java#L621

That is really the only thing i can find. The work is extremely complete with both tests and documentation. Nice work!

-Justin

On Mon, Jul 9, 2012 at 12:01 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

All,

With the migration to Git and creation of branch 2.2.x done, I’d like to gather feedback on a proposed enhancement to the REST API that I worked on a few weeks ago, which adds configuration options for global settings and OWS services. I wrote a GSIP with the high level description of changes introduced at the following URL:

http://geoserver.org/display/GEOS/GSIP+76±+Extend+REST+API+to+configure+settings+and+OWS+services

The associated patch with unit tests and documentation for these changes is attached in the corresponding JIRA ticket at:

https://jira.codehaus.org/browse/GEOS-5122

Thanks


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@anonymised.comsts.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel


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

On Mon, Jul 9, 2012 at 8:01 PM, Juan Marín Otero
<juan.marin.otero@anonymised.com> wrote:

All,

With the migration to Git and creation of branch 2.2.x done, I'd like to
gather feedback on a proposed enhancement to the REST API that I worked on a
few weeks ago, which adds configuration options for global settings and OWS
services. I wrote a GSIP with the high level description of changes
introduced at the following URL:

http://geoserver.org/display/GEOS/GSIP+76+-+Extend+REST+API+to+configure+settings+and+OWS+services

The associated patch with unit tests and documentation for these changes is
attached in the corresponding JIRA ticket at:

https://jira.codehaus.org/browse/GEOS-5122

Looking good, I have one question related to how the REST interface is used.
As far as I can see a POST is allowed if the settings to be configured
is missing,
and a PUT only if it's already there, see for references:
http://stackoverflow.com/questions/630453/put-vs-post-in-rest
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/

As far as I know PUT can be used also for resource creation in REST, the
discriminant between using POST and PUT is that with POST you don't
know where the resource is going to end up, while with PUT you already
know the location at which the resource should be created.

Given that the settings have fixed locations that can be foreseen, wouldn't
it make more sense to just use PUT for both creation and updates,
and remove POST support?

Cheers
Andrea

--
Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf

Sorry, added the links to the references on the usage of POST and PUT
in the wrong place, they
were meant to follow my statement about the usage of POST and PUT, that is:

------------------------------------------------------------------------------------------------

As far as I know PUT can be used also for resource creation in REST, the
discriminant between using POST and PUT is that with POST you don't
know where the resource is going to end up, while with PUT you already
know the location at which the resource should be created, see for reference:

http://stackoverflow.com/questions/630453/put-vs-post-in-rest
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/

-------------------------------------------------------------------------------------------------

Cheers
Andrea

--
Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf

I agree with Sean, er i mean Andrea :stuck_out_tongue: that simply using PUT for these types of services makes sense. The geoserver restconfig api uses the convention (and i believe this is consistent with the links Andrea posted) that POST is generally only used when POSTING to a collection in order to create a new entry where the contents of the collection are the same “type”. WHere as here under the “/services” collection we are talking about entities of different types and furthermore just one entity of each type.

On Wed, Jul 11, 2012 at 3:21 AM, Andrea Aime <andrea.aime@anonymised.com> wrote:

Sorry, added the links to the references on the usage of POST and PUT
in the wrong place, they
were meant to follow my statement about the usage of POST and PUT, that is:


As far as I know PUT can be used also for resource creation in REST, the
discriminant between using POST and PUT is that with POST you don’t
know where the resource is going to end up, while with PUT you already

know the location at which the resource should be created, see for reference:

http://stackoverflow.com/questions/630453/put-vs-post-in-rest
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/


Cheers
Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@anonymised.comsts.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel


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

Hey Justin,

On Mon, Jul 9, 2012 at 10:44 PM, Justin Deoliveira <jdeolive@anonymised.com> wrote:

Hey Juan,

All in all this proposal looks great. Nice work man.

Thanks a lot for taking a look at it

One thing though is about the ServiceInfo object representations. I would expect them to match the representation stored on disk for the data directory. Its understandable why though don’t through since there is a secondary interfaces / set of classes used for this loaded by extension point.

This makes sense, I guess I overlooked these and went straight to ServiceInfo and didn’t consider that there would be an extension point for this. I agree, the xml should reflect what is on disk like we do with other resources.

The extension point is XStreamServiceLoader and you’ll find subclasses for each of the ows services. I think we should use this for the xml and json representations of service objects. For an example of how to use the extension point see:

https://github.com/geoserver/geoserver/blob/master/src/main/src/main/java/org/geoserver/config/GeoServerLoader.java#L621

I see how this class is loaded and have found the subclasses you mention (WCSXStreamLoader, etc…) but I’m not sure which object you’re referring to when you say “we should return this for the xml and json representations of service objects”. Do you mean that I should use the load method to return the specific ServiceInfo (i.e. WCSInfo) object that these subclasses use? Something else? Sorry maybe I’m misunderstanding something obvious but want to make sure.

That is really the only thing i can find. The work is extremely complete with both tests and documentation. Nice work!

Thanks

-Justin

On Mon, Jul 9, 2012 at 12:01 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

All,

With the migration to Git and creation of branch 2.2.x done, I’d like to gather feedback on a proposed enhancement to the REST API that I worked on a few weeks ago, which adds configuration options for global settings and OWS services. I wrote a GSIP with the high level description of changes introduced at the following URL:

http://geoserver.org/display/GEOS/GSIP+76±+Extend+REST+API+to+configure+settings+and+OWS+services

The associated patch with unit tests and documentation for these changes is attached in the corresponding JIRA ticket at:

https://jira.codehaus.org/browse/GEOS-5122

Thanks


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel


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


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

On Wed, Jul 11, 2012 at 4:26 PM, Justin Deoliveira <jdeolive@anonymised.com> wrote:

I agree with Sean, er i mean Andrea :stuck_out_tongue: that simply using PUT for these types of services makes sense. The geoserver restconfig api uses the convention (and i believe this is consistent with the links Andrea posted) that POST is generally only used when POSTING to a collection in order to create a new entry where the contents of the collection are the same “type”. WHere as here under the “/services” collection we are talking about entities of different types and furthermore just one entity of each type.

On Wed, Jul 11, 2012 at 3:21 AM, Andrea Aime <andrea.aime@anonymised.com> wrote:

Sorry, added the links to the references on the usage of POST and PUT
in the wrong place, they
were meant to follow my statement about the usage of POST and PUT, that is:


As far as I know PUT can be used also for resource creation in REST, the
discriminant between using POST and PUT is that with POST you don’t
know where the resource is going to end up, while with PUT you already

know the location at which the resource should be created, see for reference:

http://stackoverflow.com/questions/630453/put-vs-post-in-rest
http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/


Cheers
Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel


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


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

Cheers
Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf

On Wed, Jul 11, 2012 at 2:03 PM, Andrea Aime <andrea.aime@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

To reiterate my take I think post should be used when you have a homogeneous collection of items that has no fixed size. I don’t think any of new endpoints meet this criteria.

Cheers

Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


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

As long as we are talking REST; I got to talk to a few GeoServer users over coffee and they indicated that the REST api was not “complete” with respect to letting them back up and restore a configuration outside of their app. Apparently for managing styles they could successfully remove a style, in order then replace it with an older version. But for many of the other resource types there was no way to remove and replace.

They assumed that this was obvious and we would be working on it; I very much requested a bug report and patch.


Jody Garnett

On Thursday, 12 July 2012 at 9:53 AM, Justin Deoliveira wrote:

On Wed, Jul 11, 2012 at 2:03 PM, Andrea Aime <andrea.aime@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

To reiterate my take I think post should be used when you have a homogeneous collection of items that has no fixed size. I don’t think any of new endpoints meet this criteria.

Cheers

Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


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


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

Separate thread please.

On Wed, Jul 11, 2012 at 8:01 PM, Jody Garnett <jody.garnett@anonymised.com> wrote:

As long as we are talking REST; I got to talk to a few GeoServer users over coffee and they indicated that the REST api was not “complete” with respect to letting them back up and restore a configuration outside of their app. Apparently for managing styles they could successfully remove a style, in order then replace it with an older version. But for many of the other resource types there was no way to remove and replace.

They assumed that this was obvious and we would be working on it; I very much requested a bug report and patch.


Jody Garnett

On Thursday, 12 July 2012 at 9:53 AM, Justin Deoliveira wrote:

On Wed, Jul 11, 2012 at 2:03 PM, Andrea Aime <andrea.aime@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

To reiterate my take I think post should be used when you have a homogeneous collection of items that has no fixed size. I don’t think any of new endpoints meet this criteria.

Cheers

Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


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


Live Security Virtual Conference
Exclusive live event will cover all the ways today’s security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/


Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel


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

Andrea, Justin

Thanks for the feedback on this, and sorry for getting back to you so late but some things got in the way (including vacation). I’ve incorporated the suggestions made by you, namely:

  1. Change all endpoints to use PUT for both creation and update (no POST), following the convention used by GeoServer’s REST API described by Justin
  2. Make sure the XML/JSON representation is the same one used when serializing to disk, by using the XStreamServiceLoader extension point and its corresponding subclasses to load and save the configuration for ServiceInfo objects.

The patch has been updated (code, documentation and tests) in the corresponding JIRA ticket:

https://jira.codehaus.org/browse/GEOS-5122

Thanks

On Wed, Jul 11, 2012 at 7:53 PM, Justin Deoliveira <jdeolive@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 2:03 PM, Andrea Aime <andrea.aime@anonymised.com.1268…> wrote:

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

To reiterate my take I think post should be used when you have a homogeneous collection of items that has no fixed size. I don’t think any of new endpoints meet this criteria.

Cheers

Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


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


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com

Great stuff Juan. Commented on the jira ticket.

On Wed, Aug 1, 2012 at 7:32 AM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea, Justin

Thanks for the feedback on this, and sorry for getting back to you so late but some things got in the way (including vacation). I’ve incorporated the suggestions made by you, namely:

  1. Change all endpoints to use PUT for both creation and update (no POST), following the convention used by GeoServer’s REST API described by Justin
  2. Make sure the XML/JSON representation is the same one used when serializing to disk, by using the XStreamServiceLoader extension point and its corresponding subclasses to load and save the configuration for ServiceInfo objects.

The patch has been updated (code, documentation and tests) in the corresponding JIRA ticket:

https://jira.codehaus.org/browse/GEOS-5122

Thanks

On Wed, Jul 11, 2012 at 7:53 PM, Justin Deoliveira <jdeolive@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 2:03 PM, Andrea Aime <andrea.aime@anonymised.com> wrote:

On Wed, Jul 11, 2012 at 8:37 PM, Juan Marín Otero <juan.marin.otero@anonymised.com> wrote:

Andrea / Justin,

Thanks for the feedback, I actually went back and forth with this a bit but ended up doing it the way the patch reflects and I don’t even remember my reasoning but yours is sound, this should be an easy change. Am I reading correctly in that you consider that POST should not be used for any of these additional resources?

Err… I guess not. I mean, when a resource location is 100% predictable and there is even a finite set of them,
POST seems overkill. Just my two cents, I’m not a REST guru

To reiterate my take I think post should be used when you have a homogeneous collection of items that has no fixed size. I don’t think any of new endpoints meet this criteria.

Cheers

Andrea


Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf


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


Juan Marín Otero
GIS Consultant

-------Visita mi blog en---------------------
http://guachintoneando.blogspot.com


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