Create a RESTful API for Mapbender
From MapbenderWiki
Contents |
RESTful API for Mapbender
- Student
- Vikas Banjara
- Mentor
- Arnulf Christl
Abstract
Mapbender is the software and portal site for geodata management of OGC OWS architectures. Currently, Mapbender interacts with the administrator through a web interface. I propose to design and implement a RESTful API for interaction with the administrator. Basic functionalities will include - Authentication with Mapbender and OGC WMS resource CRUD. The project will include design of the representation following the resource oriented pattern and the implementation of the API in PHP.
Introduction
Mapbender is the software and portal site for geodata management of OGC OWS architectures. The software provides web technology for managing spatial data services implemented in PHP, JavaScript and XML. It provides a data model and interfaces for displaying, navigating and querying OGC compliant map services. The Mapbender framework furthermore provides authentication and authorization services, OWS proxy functionality, management interfaces for user, group and service administration in WebGIS projects.
Currently, Mapbender interacts with the administrator through a web interface. I propose to design and implement a RESTful API for interaction with the administrator. Basic functionalities will include - Authentication with Mapbender and OGC WMS resource CRUD (Create, Retrive, Update and Delete). An OGC WMS resource has various representations. Some of them are standardized which includes - Capabilities document, GetMap "Operation" etc.. The project will include design of the representation following the resource oriented pattern and the implementation of the API in PHP. Background
As mentioned above, Mapbender currently interacts with the administrator through a web interface, it becomes difficult to automate the administration part of the software. We always need a human to use the interface to manage WMS. The main motivation of this project is to automate the administration part so that updates etc can be done automatically without human intervention.
The idea
I propose to design and implement a RESTful API for Mapbender. Currently, Mapbender administration is being handled by a web interface. This requires a human being to manage the WMS. The proposed RESTful API will help to automated the management.
Main functionalities of the API will be -
- Authentication with Mapbender.
- OGC WMS resource CRUD (Create, Retrieve, Update and Delete).
Authentication with Mapbender can be done in two ways - plain username/password method and OAuth protocol. I will first implement the plain username/password method and then in the end will implement the OAuth protocol (if time permits). Plain username/password authentication can be implemented by using PHP and querying the database for the credentials. OAuth protocol is a standard protocol which can be implemented in PHP.
OGC WMS resource has various representations. Some of them are already well defined and standardized including the Capabilities document, GetMap operation, etc.. Some of the representations are not well defined yet. One aim of the project includes design of the representations following resource oriented pattern.
Designing the RESTful API precisely include following points -
1. Identify the resources and accordingly define the URIs
2. Deciding the data format for each resource (Representation of the resource).
3. Methods supported at each URI (operations supported for each resource).
4. Deciding the response and status code to be returned to the client.
And in more detail -
1. Figure out the data set.
2. Split the data set into resource.
For each kind of resource -
3. Name the resource with URIs
4. Expose a subset of the uniform interface
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate the resource into existing resources, using hypermedia link and forms
8. Consider the typical course of events: event flow
9. Handle the error conditions (an example of error coudl be Update on a non existing resource).
Backend of the API will be implemented in PHP. As we all know that in REST we use the standard HTTP methods (POST, GET, PUT, DELETE) to communicate. The clients can use cURL library of PHP to send HTTP requests -
GET - Retrieve of CRUD, is used to retrieve a resource from the server side. POST - Create of CRUD, is used to create a resource on the server side. PUT - Update of CRUD, is used to update an existing resource on the server side. DELETE - is used to delete a resource on the server side.
Flow of events during an API call will be -
1. Sending the request from the client side
2. Evaluating the request and sending the response on the server side.
3. Evaluating the response on the client side.
On the server side, evaluating the request involves following steps -
1. Parsing the URI to identify the resource
2. Retrieve the HTTP method which is stored in the variable $_SERVER['REQUEST_METHOD']
3. Retrieve the data from the request (if HTTP request is POST or PUT)
4. Sending the response with proper HTTP code.
Project plan
During Community Bonding Period - Read more about the RESTful design principles.
I have already installed mapbender on my local computer. I will go through the Mapbender admin interface and understand them well.
After GSoC starts - First three weeks
I will work with the mentor to decide the resources to be exposed. Decide the representation of the resource. What methods to be exposed for each resource. Designing will be the most crucial part of this project. So, I want to spend atleast first three weeks on preparing a design document for the API. This document will help in future also as a documentation.
Update the Category:Glossary of the project to describe the use of the terms "clients", "server", "back end", "application", etc. in the context of the project.
After first three weeks to Mid-term
- work on the authentication with Mapbender. I will start with the plain username/password method.
- work on the server side evaluation of requests and sending response.
- use a test driven development method and follow the Scrum process with daily scrums (as the availability of mentor and student will allow).
After mid-term (3 weeks)
- Work on the client side of the API. I will use cURL PHP library to design the client side of the API.
- Work on the client side handling of the response.
Next one week
Error handling (wherever required)
Next two week
Release the API to mapbender developer community for checking.
Meanwhile I would work on implementing the OAuth protocol for authentication. OAuth is a standard protocol, so only implementation is required
Till end-term evaluation
- Bug fixing, documentation.
- I will look for suggestions from the dev community.
- I will also add in the possible future enhancements.
- Note:
The project roadmap is tentative and it can be changed according to the project requirements during the actual implementation period.
Acknowledgements
- Arnulf - For making me understand about Mapbender in detail and giving so many constructive suggestions throughout.
- Christoph Baudson - His blog was really helpful
- spsneo - He helped me out in understanding the RESTful API fundamentals and his suggestions in writing the application.
- Wikipedia - Article on REST was really helpful
Future ideas / How can your idea be expanded?
The RESTful API for Mapbender can be extended for more WMS representations in future. It can be used for automating the WMS management task. Answer the following questions briefly (about 300 words max) How does your SoC task benefit the OSGeo member project, and more generally the OSGeo Foundation as a whole?
The RESTful API project will make it easier to integrate Mapbender with other projects. It will also allow machine access to the management back end data and improve the use of the project as centralized management back end for spatial data infrastructures. This will further improve the USP of the project.
