An increasing number of our partners are talking about ‘integrating systems’ to show their project information on their website. Right now Akvo RSR makes this possible through four methods – Akvo Pages, Akvo Widgets, Akvo Sites and the API (see the Akvo RSR product page for a comparison). Much is possible using the RSR API, but there are often different expectations of what an API does and doesn’t do. So here’s some background information about what an API is, and also the ways the Akvo RSR API can be used. As there are different use options, it’s worth taking some time to determine which solution meets your needs.
What is an API?
An API – or Application Programming Interface – generally refers to the way in which a programme can be interfaced with by another programme.
Historically if you had a piece of information in one place, and wanted to display this information in another place, you would need to read and ‘copy’ the data, and then ‘paste’ it where you wanted it to go.
This approach is very simple and easy to set up for small data sets or where changes are infrequent. But as the information grows or is updated more frequently, this manual process becomes unmanageable. Mistakes can be made from human error; it may be difficult to determine how up-to-date a piece of information can be and an unsynchronised process can quickly turn messy.
As technology moves forward, we are seeing much smoother and more efficient ways to transfer information around like this. Akvo RSR has API functionality to help tackle this very problem.
Akvo RSR’s web API handles data in two different text formats (JSON and XML) that can be read or created by another system without the need for a person to sit in between. This allows synchronisation to be automated and ensures that the correct data is available in the right places at the right time.
How can partners use the Akvo RSR API?
There are two very distinct functions that can be provided by the API for two very different use-cases. When considering implementing an API solution, we need to determine which of the two options provide the solution you are looking for, or whether a combination of both options are needed.
Option 1: the READ API
What is it?The Read API allows information that is currently stored in RSR to be used somewhere else, either on the web or within an organisation’s internal systems.
When is it used?When your organisation:
- has an existing project portfolio in RSR, or has plans to create/import project information into RSR;
- would like to visualise this project information on your corporate website in own branding and style, and use RSR directly to update project information;
- has technical capabilities for website API integration and design.
ImplementationThis process is easy to activate, is fully documented and functional within RSR and can be offered to new and existing partners with few limitations. Further implementation documentation can be found here.
ExamplesCommonSites, Millennium Water Alliance (MWA) and others.
Option 2: the WRITE API
What is it?The Write API provides a portal for your organisation to copy project data from an internal or existing data source such as a project management system (PMS) and load this into RSR, removing the need for new projects to be re-entered into RSR manually.
When to use it?When your organisation:
- has a large project portfolio (more than 100 projects);
- would like to show the project information within RSR;
- has a limited portfolio (or none) already existing in RSR;
- has an existing portfolio within an internal project management system. Using the Write API allows you to continue to manage your portfolio from within your own systems, while the changes being made are then reflected within the RSR project data;
- has the commitment to open up your project portfolio to the public, as an implementation of the API in this way leads to publicising of previously internal project information;
- (may be) exporting your portfolio to the IATI standard;
- has technical capabilities for data management, output configuration and integration synchronisation.
ImplementationThe product implementation for this feature is in-depth and not available ‘off the shelf’, but requires a custom implementation project to be carried out to successfully execute.
ExamplesThere are only use-examples of partners implementing the Write API in combination with the Read API. Cordaid is in the process of bringing online their project portfolio this way. You can read about it in this blog and in this blog. The RAIN Foundation is currently also implementing a similar solution.
(Update 13 August 2014: Cordaid’s implementation is now live and RAIN Foundation’s is imminent.)
Key questions
To help the decision making process these are the key questions to consider:
- What does your organisation want to do exactly, and why? Keep in mind that visualisation of project information on a website is possible without the need to integrate your project management system.
- How many projects are we talking about? Only with a large number of projects it is worth the effort to integrate a project management system with RSR.
- Is project information readily available? If yes, how much and where is it stored?
- What is the time frame?
More information
Specific information about the RSR API can be found on the Akvo RSR API developer documentation page. For questions about the use of the RSR API, please contact Adrian [at] akvo.org or Pelle [at] akvo.org.
Blog by Adrian Collier, product manager RSR and Charlotte Soedjak, project manager at Akvo in Amsterdam.