Custom_Webservice¶ ↑

This plugin is a simple example of how to provide custom web services for your Redmine. By starting from this template, you can write only a few lines of Ruby code and add powerful query or update functions to your Redmine.

As the Redmine REST API becomes more complete, this will hopefully be less necessary, but for now there are many missing functions in the REST API and the state of implementation varies from Redmine release to release, so we found it more useful to put the code our external tools rely on in our own plugin that can be stable across releases and versions.

That said, almost everything you would do with this plugin (with the possible exception of some query stuff) will eventually mostly migrate to using the REST API. In the meantime, enjoy.

Install and Setup¶ ↑

This plugin installs normally:

1. cd vendors/plugins in your Redmine install. A test install is recommended!

2. git clone git://github.com/leovitch/custom_webservice.git

3. Run or restart Redmine

   • The examples in the code all assume you’re testing under Mongrel by using this command at the root.

   • RAILS_ENV=production ruby script/server

4. Go to the Administration > Settings > Authentication page and make sure the box “Enable REST Web Service” is on.

5. For testing, log in as the admin user, go to the “My Account” page, and copy the API key. You’ll need it for testing.

6. Some of the samples are project-specific. For the projects you want to test, go to the project > Settings > Modules page and enable “Custom Web Services”.

7. Now you can test the samples from the shell using curl (or wget). See the class documentation for CustomWebserviceController.

8. Once you see how the samples work, delete those actions and make some useful new actions of your own.

   • You’ll probably find custom_webservice/app/controllers/custom_webservice_controller.rb is the only file you need to modify.

9. Once you’ve got the tests working, you’ll want to make a separate user for the API accesses. Unfortunately, it’s not practical to make a non-admin user at the moment.

10. If you deploy web services based on this plugin, here are a couple points to be aware of.

    1. Be sure to delete the non-authenticated actions at the top of the controller. They’re only there to help you understand and try out some simple actions.

    2. In general, to avoid POST forgeries, API keys are only secure if used over https or on a totally trusted LAN segment.

Copyright © 2011 Leo Hourvitz, released under the MIT license