REST API Code Sprint Prep
In our previous blog post we highlighted the GeoServer Code Sprint 2017 taking place at the of this month. We are all looking forward to GeoSolutions hosting us in beautiful Tuscany and have lots of work to do.
One of the secrets (and this comes as no surprise) to having a successful code sprint is being prepared. With this year’s REST API migration from restlet to spring model-view-controller we want to have all technical decisions made, and examples for the developers to work from, prior to any boots hitting the ground in Italy.
But before we get into the details …
Code Sprint Sponsors
We would like to thank our sprint sponsors - we are honoured that so many organizations have stepped up world wide to fund this activity.
Gaia3D is a professional software company in the field of geospatial information and Earth science technology. We would like to thank Gaia3D for their gold sponsorship.
Insurance Australia Group (IAG) is our second gold sponsor. This is a great example of open source being used, and supported, by an engineering team. Thanks to Hugh Saalmans and the Location Engineering team at IAG for your support.
Boundless is once again sponsoring the GeoServer team. Boundless provides a commercially supported open source GIS platform for desktop, server, mobile and cloud. Thanks to Quinn Scripter and the Boundless suite team for their gold sponsorship.
How 2 Map is pleased to support this year’s event with a bronze sponsorship.
I am overjoyed FOSSGIS (German local OSGeo chapter) is supporting us with a bronze sponsorship. This sponsorship means a lot to us as the local chapter program focuses on users and developers; taking the time to support our project directly is a kind gesture.
Sponsorship Still Needed
While we have a couple of verbal commitments to sponsor - we are still $1500 USD off the pace. If your organization has some capacity to financially support this activity we would dearly love your support.
This is an official OSGeo activity; any excess money is returned to the foundation to help the next open source sprint. OSGeo sponsorship is cumulative. Check their website for details on how your helping out the geoserver team can be further recognized.
For sponsorship details visit the wiki page (or contact Jody Garnett for assistance).
Update: Since this post was published we are happy to announce new sponsor(s).
Thanks to Caroline Chanlon and the team at Atol Conseils et Développements for bronze sponsorship.
Update: Thanks to David Ghedini (acugis.com) and others donating smaller amounts via the OSGeo paypal button.
Getting Ready for REST
In this week’s GeoServer meeting we had a chance to sit down and plan out the steps needed to get ready.
The majority of prep will go into performing the restlet to spring mvc migration for a sample REST API end point to produce a “code example” for developers to follow. We have selected the rest/styles endpoint as one of the easier examples:
Preflight check: Before we start we want to have a good baseline of the current REST API responses. We would like to double check that each endpoint has a JUnit test case that checks the response against a reference file. Most of our tests just count the number of elements, or drill into the content to look for a specific value. The goal is to use these reference files as a quick “regression test” when performing the migration.
Migrate rest/styles from StyleResource (restlet) to StyleController (spring): This should be a bit of fun, part of why spring model-view-controller was selected. Our goal is to have one Controller per end-point, and configure the controller using annotations directly in the Java file. This ends up being quite readable with variable names being taken directly out of the URL path. It is also easier to follow since you do not have to keep switching between XML and Java files to figure out what is going on. It is important that the example is “picture perfect” as it will be used as a template by the developers over the course of the sprint, and will be an example of the level of quality we expect during the activity.
Create StyleInfo bindings (using XStream for xml and json generation): The above method returns a StyleInfo data structure, our current restlet solutions publishes each “resource” using the XStream library. We think we can adapt our XStream work for use in spring model-view-controller by configuring a binding for StyleInfo and implementing in using XStream. _This approach is the key reason we are confident in this migration being a success; existing clients that depend on exactly the same output from GeoServer - should get exactly the same output. _
StyleController path management: There is some work to configure each controller, while we have the option of doing some custom logic inside each controller we would like to keep this to a minimum. _This step is the small bit of applicationContext.xml configuration work we need to do for each controller, we expect it to be less work then reslet given the use of annotations. _
Reference Documentation Generation: We are looking into a tool called swagger for documentation generation. Our current reference documentation only lists each end-point (and does not provide information on the request and response expected - leaving users to read the examples or try out the api in an ad-hoc fashion). See screen snap below, our initial experience is positive, but the amount of work required is intimidating.
Updated examples for cURL and Python: We would like to rewrite our examples in a more orderly fashion to make sure both XML and JSON sample requests and responses are provided. Ideally we will inline the “reference files” from the JUnit regression test in step 1 to ensure that the documentation is both accurate and up to date.
You can see a pretty even split in our priorities between performing the migration, and updating the documentation. We believe both of these goals need to be met for success.
Next stop Tuscany
Although this blog post focuses on the sponsorship/planning/logistics side of setting up a code sprint there is one group without whom this event could not happen - our sprint participants and in-kind sponsors (providing a venue & staff).
Thanks to GeoSolutions for hosting us, and to Astun, Boundless, GeoSolutions for the hands-on participation that makes this sprint possible
For more information:
Java 2017 Code Sprint (OSGeo Wiki) used for planning and logistics
REST API Refresh (GeoServer Wiki) code example and technical decisions
- OGC Filter Injection Vulnerability Statement
- GeoServer 2.22.0 Release
- GeoServer 2.21.2 Release
- Jiffle and GeoTools RCE vulnerabilities
- GeoServer 2.20.4 Released
- Spring4Shell RCE vulnerability
- GeoServer 2.20.3 Released
- GeoServer 2.19.5 Released
- GeoServer 2.19.4 Released
- Log4J2 zero day vulnerability assessment