Implementing the Open Supporter Data Interface (OSDI) API for CiviCRM - GSoC Concluding Blog Post

Published
2015-08-27 13:55
Written by

Hi again, I'm Anudit Verma, a sophomore undergraduate student pursuing Computer Science and Engineering at University School of Information and Communication Technology, in New Delhi, India.
This year I worked on Open Supporter Data Interface (OSDI) API implementation into CiviCRM project as a 2015 Google Summer of Code student. This is my second blog post in which I will be concluding and summarizing the work I have done past this summer.

You can look at the introductory blog post which was posted at the start of the coding period here:
https://civicrm.org/blogs/anudit-verma/implementing-open-supporter-data-interface-osdi-api-civicrm
 

Looking back at the 'Overview'

The OSDI API implementation is in line with CiviCRM's mission to be an open platform for organizations of all sizes. Creating the implementation will allow them to use the OSDI API easily. The existence of a common API will reduce progressive data vendors’ customer costs related to moving data between different systems, lower integration costs and enhance the ability of innovators to create products for the marketplace. You can learn more about OSDI at www.opensupporter.org
 

The 'org.civicrm.osdi' Extension

The OSDI implementation project was developed as an extension for CiviCRM. This extension act as a connecting bridge between two systems one having OSDI implementation and the one using this extension. It can performs GET request to retrieve the people's data from the implemented system based on OSDI specifications. It includes 'Person Sign-up Helper' which is a helper endpoint to aid in the creation of People resources via POST requests. This extension utilizes REST API calls, you can GET the desired data or perform various actions like POST, PUT and DELETE through the REST interface.

AEP : API Entry Point

To explore the people's data on the server AEP was constructed which is a part of the OSDI specification. The AEP helps in exploring the various endpoints like people's collection, individual person's record, brand logo etc. Also AEP has 'Person Sign-up Helper' for creation of new individual resources.

[[{"type":"media","view_mode":"media_responsive","fid":"19902","attributes":{"alt":"","class":"media-image","style":"max-width:1853px;","width":"100%"}}]]



This extension is capable of handling the following actions, let's look up to them briefly:

  • GET -requests are automatically invoked when you want to retrieve the People's data or any individual person's data. You can look up to the desired data through the API explorer on your own CiviCRM site at /civicrm/api (available from the menubar at Help -> Developer -> Api Explorer). Also you can execute a REST call having entity as 'People' and action as 'get' passing along the user key and site key, parameters like options or limits can be added to these REST URI requests.

    [[{"type":"media","view_mode":"media_responsive","fid":"19907","attributes":{"alt":"","class":"media-image","style":"max-width:1850px;","width":"100%"}}]]
  • POST -these requests are used to add a new person's record into the system. The 'Person Sign-up Helper' accepts these requests in JSON format having fields' name according to OSDI specification.To POST a new record click on the NON-GET button (orange color) and provide the data in JSON format. The fields provided should be based OSDI specification in order to get this request accepted into the system.

    [[{"type":"media","view_mode":"media_responsive","fid":"19904","attributes":{"alt":"","class":"media-image","style":"max-width:1012px;","width":"100%"}}]]

  • PUT -This is primarily used to update an existing person's record. You need to provide the 'Method' while using the HAL-browser interface at the person's endpoint whose record has to be updated.

    [[{"type":"media","view_mode":"media_responsive","fid":"19905","attributes":{"alt":"","class":"media-image","style":"line-height:1.5;max-width:928px;","width":"100%"}}]]
     
  • DELETE -It deletes the person's record. Similarly, just fill the 'Method' field as 'DELETE' to remove that record.

    [[{"type":"media","view_mode":"media_responsive","fid":"19906","attributes":{"alt":"","class":"media-image","style":"line-height:1.5;max-width:1806px;","width":"100%"}}]]

Using the extension
You can follow the documentation present in the GitHub repository of this project. Here : https://github.com/anuditverma/org.civicrm.osdi

Conclusion
This project fulfills the basic requirements to be considered as an extension for implementing OSDI into the CiviCRM system. The 'Person Sign-up Helper' is developed to post a new record into the system based on OSDI specification. Similarly, various actions like GET, POST, PUT and DELETE are used to perform control actions as per OSDI specification. So as per GSoC and other mandatory fulfillments this project stands complete. Right now, its alpha version would be released and uploaded on the CiviCRM extension directory. Though I would continue contributing to the Git Hub repository, testing the extension more, fixing self-raised issues and issues reported by others. I would add more helpers which are defined in the OSDI specification.

Acknowledgments
I would like to thanks Joe McLaughlin and Eileen McNaughton who were the mentors assigned to me for this project.

  • Joe Sir, thank you for believing in me as many may not be knowing that originally I applied in CiviCRM with a different proposal which was not very much similar from this project. So I am very thankful for selecting me and how we worked together in understanding OSDI by attending the weekly OSDI Technology Committee meetings which was very helpful for moving ahead in the completion of this project.
  • Eileen ma'am, we had a time zone difference in which it was sometimes difficult to match our work timings. Despite of this I am very much grateful to you as whenever I had a query regarding CiviCRM you always responded in quickly whether it was late in night at your end or us hanging out on IRC for hours. So thank you for assisting me in understanding CiviCRM.
  • I would like to thanks Joe Murray who encouraged me and pushed me ahead when I needed the most. Thank you Sir for advising me on setup-ing my development environment and helping on other Civi issues.
  • Thanks to Jason Rosenbaum from Action Network who helped me getting an insight on an existing OSDI implementation at their organization. Well Jason and I discussed on the issues he raised on my Git Hub repository which helped this implementation work effectively and as per OSDI specification. So thanks to him for contributing his time in this project.
  • Josh Cohen, founder of OSDI for hosting weekly online OSDI Technology Committee meetings that helped me gain knowledge about OSDI significantly.
  • Edsel Roque Lopez, who works for JMA consulting, Joe Murray got us introduced to each other. We share same time zone and Edsel's expertise on CiviCRM also helped me a gain a lot about background working of this software. So Thanks to him as well for contributing his valuable time into this project.
  • Thanks to Timothy Anderegg for joining in the discussioin of this project and for sharing your valueble thoughts on it.

See Also

 

Filed under

Comments

Anudit, you are to be commended for your unfailing politeness and eventual persistence in completing this project. Thanks for the useful work.

One small note about this post: would the example DELETE cause the deletion of all persons in the CiviCRM database? Wouldn't a more common use case be to delete a specific person based on their external_identifier or email + first_name + last_name? Perhaps you could provide an image of that instead of the empty body one above.

Best wishes,

Joe

 

Thank you so much Sir.
 
Actually DELETE works only on person's endpoint and removes only one record at once, so if we want to remove a person then we can trigger a NON-GET request present on the self-link of that person or we can navigate to that individual record from People’s collection via self-link button. Then eventually by performing a DELETE action by specifying the “Method’’ through NON-GET interface we can remove that person without the need to provide any external_identifier or any other details.
 
So the image, it doesn’t have any JSON request like civicrm_id or any unique identifier within its body. I agree that the image might be unclear so I need to specify this image with a caption like we can observe the details of the person which is being grey shadowed behind the NON-GET interface whose record is about to get removed. So I will try to add more details and explanation about DELETE along with a more suitable image.
 
Thanks.