anuditverma / org.civicrm.osdi Goto Github PK

View Code? Open in Web Editor NEW

1.0 1.0 3.0 84 KB

OSDI API Implementation for CiviCRM - Google Summer of Code (GSoC) 2015

License: Other

PHP 100.00%

gsoc osdi civicrm osdi-specifications osdi-api

org.civicrm.osdi's Introduction

Implementing the Open Supporter Data Interface (OSDI) API for CiviCRM

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

About org.civicrm.osdi Extension

The org.civicrm.osdi 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. The rest interface works like the AJAX interface, with one major difference: each call requires an api_key (user key) & key (site key) parameter. And there has to be a user with that api_key having sufficient permissions. We will see how to set these keys within the CiviCRM dashboard and also how to add these keys at various placeholders present within the code. 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.
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.
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.
DELETE -It deletes the person's record. Similarly, just fill the 'Method' field as 'DELETE' to remove that record.

All these actions can be easily tested on this explorable browser which can be git cloned at your root of the server. HAL-browser is an API browser for exploring hal+json type media. You can also perform these specified actions above through its interface. A NON-GET request can be made through the HAL-browser for executing POST, PUT and DELETE requests.

Getting Started

Installation

Pre-requisite:
Assuming you have an up and running CiviCRM site.
You need to enable extensions in CiviCRM.
Next Steps:
Then git-clone this extension : git clone https://github.com/anuditverma/org.civicrm.osdi.git
On the terminal navigate to sites/all/libraries and install this Nocarrier\Hal library. You can follow the documentation of this library or alternatively just run this command : composer require nocarrier/hal

Setting up keys

You need to set site key and API key before using the REST interface.

You need to know your site key which can be found in the civicrm.settings.php file labeled CIVICRM_SITE_KEY.
There are two methods of creating an API key for an individual user.
Manual Method : You can enter the key directly in the database table civicrm_contact into the field api_key using your database tool. That would normally be phpmyadmin, MySQL Workbench etc
API Key Extension : You can use this extension found here which would make the whole process much easier.

Configure the extension -Adding yoursite URL and keys

Now to make this extension work you need to provide your site URL (www.example.com) and the keys which were set in the previous steps. You need to add these values in the following files. (Helper comments are present in these codes in order to set the values easily)

signup.php -Person Sign-up Helper- accepts POST requests to add a new person's record to the system.
blank.php -eliminates empty fields (under development)
index.php -retrieves (GET) collection of people.
person.php -shows details about individuals and handles PUT & DELETE requests.

Setup Hal-browser (Optional)

You can git clone the HAl-browser to the site root of your server. git clone https://github.com/mikekelly/hal-browser.git
To access the HAL-browser just open the 'browser.html' file present in 'hal-browser' directory of your web root. -In accordance with this you need to use this CiviCRM-OSDI-Files repository for adding API Entry Point (AEP) to your server from where you can explore the data of your site and see the working of GET, POST, PUT & DELETE requests in action.
In order to access the AEP you need to load the osdi.php file into the HAL-browser and then you can explore the other APIs' ends.

Usage

Having this extension up and running on your site, you can use HAL-browser to request POST (GET) and NON-GET (POST, PUT & DELETE) requests to your own site. Also you can do the same from your site to an another site where this extension is enabled.
For exchanging the data between these two said sites, you just need to change the site URLs to the URLs of the target site and also you need to know the API key and SITE key of that target site and then change these values in the code by following these steps mentioned above.
Follow this example to know more about NON-GET (POST, PUT & DELETE) requests.

Updating

To update the extension follow the steps,

Disable the extension first (Go to Administer -> System Settings -> Manage Extensions)
Uninstall the extension.
Then in the extension directory do a git pull via terminal.
Re-install and enable the extension again.

org.civicrm.osdi's People

Contributors

Stargazers

Watchers

Forkers

j-ro fuzionnz joemcl

org.civicrm.osdi's Issues

implement paging functions

This can be implemented after some of the other stuff, but tor the entire API, you might want to implement the paging functions as described here:

http://opensupporter.github.io/osdi-docs/#collections-and-navigation

Right now it seems you return all contacts in the Civi system with going to the people endpoint. While there aren't many, this probably works fine. Once you have thousands, or tens of thousands, or hundreds of thousands, that's going to cause extremely slow performance. Implementing paging and navigation will keep things fast.

The way we've done it, we've set the default max page size to 25. Folks can request less than that, but we've also set the overall max page size to 25 to keep things fast. You might want to talk with Eileen about what the defaults and overall max should be for a civi system.

/people endpoint: implement individual person resources

So, links like this:

/sites/default/ext/osdi/api/v3/People/index.php?id=1

That brings back just that person's resource who's ID is 1.

/people POST / person_signup_helper

The person signup helper should not be a form. It should be an API endpoint that takes a POST request. So, if I use the browser here:

http://camus.fuzion.co.nz/hal-browser/browser.html#/sites/default/ext/osdi/api/v3/People/index.php

And I click the orange non-get button next to self at the top of the left column, that'll set up a POST request to the people endpoint. There you'll receive JSON in the person_signup_helper format (or could be another endpoint if you want), and process that into a person resource.

/people endpoint: tags should not be embedded

That should be removed.

/people endpoint: links to tags, question answers, and addresses should be removed

Since these are not valid links for /people -- addresses isn't valid at all, there is no OSDI address resource. And for tags, on people, there is a link to /taggings. But since we're not implementing tags yet, I'd leave that out, and question answers.

For now, I'd only link to self, since that's all that we're implementing at the moment.

/people endpoint: created/modified_date should be in ISO format

This should be specified in the spec but it's not right now...

So something like:

2015-08-06T16:26:01Z

Rather than:

2/10/2015

/people endpoint: address isn't mapped correctly

This user:

{
        "given_name": "Kiara",
        "family_name": "Roberts",
        "email_addresses": {
          "primary": true,
          "address": "[email protected]"
        },
        "identifiers": [
          "osdi-person-[1]"
        ],
        "id": "2",
        "created_date": "2015-07-03 14:19:10",
        "modified_date": "2015/08/08",
        "custom_fields": {
          "email": "[email protected]",
          "full_name": "Kiara Roberts",
          "event_code": "xx",
          "address": "287D Martin Luther King Ave NW",
          "zip": null,
          "pledge": "3"
        },
        "postal_addresses": [
          {
            "address_lines": [
              null
            ],
            "postal_code": null,
            "address_status": "Verified/Not Verified",
            "primary": "True/False"
          }
        ],
        "phone_numbers": [
          {
            "number": null
          }
        ],
        "_embedded": {
          "osdi:tags": []
        },
        "_links": {
          "self": {
            "href": "http://api.opensupporter.org/api/v1/people/X"
          },
          "addresses": {
            "href": "http://api.opensupporter.org/api/v1/people/X/addresses"
          },
          "question_answers": {
            "href": "http://api.opensupporter.org/api/v1/people/X/question_answers"
          },
          "osdi-tags": {
            "href": "http://api.opensupporter.org/api/v1/people/X/tags"
          }
        }
      }

This user has an address in custom fields, but that doesn't show up in address lines, but it should (and be removed from custom fields).

Address verified/unverified and true/false for primary should also not be there, or should have one value, not both if this is something civi supports.

/people endpoint: blank values should be skipped

Testing here:

http://camus.fuzion.co.nz/hal-browser/browser.html#/sites/default/ext/osdi/api/v3/People/index.php

Blank values should be simply not returned. Right now, "" is being outputted for blank names, null for other blank values, etc... Instead, if there's no data, the field should be not included.

change the content-type

All endpoints should be returning the content-type application/hal+json. Right now it's returning text/html

/person endpoint : id and self link url are not in sync

I realized this one recently while DELETE-ing some last records in the database. So if someone clicks on the self link on the people endpoint for any embedded person's record it will not show the field's values to that chosen record rather will fetch the index id of the people's array (certainly a different id than the unique contact id). This then can show up the details of the person having an id equals to array index value or may return null values if there is no record having the unique contact id equals to array index value.

/people endpoint: email addresses is an array

You have:

"email_addresses": {
    "primary": true,
    "address": "[email protected]"
  }

It should be:

"email_addresses": [
          {
            "primary": true,
            "address": "[email protected]"
          }
        ]

/person endpoint : Adding PUT & DELETE support

Currently the PUT & DELETE actions are supported on the person-sign up helper, so they will be moved from there and will be added to the person's endpoint.

/people endpoint: don't replicate fields as custom fields

Right now, I'm getting resources on the test endpoint like this:

{
        "given_name": "",
        "family_name": "",
        "email_addresses": {
          "primary": true,
          "address": "[email protected]"
        },
        "identifiers": [
          "osdi-person-[0]"
        ],
        "id": "1",
        "created_date": "2015-07-03 14:19:10",
        "modified_date": "2015/08/08",
        "custom_fields": {
          "email": "[email protected]",
          "full_name": " ",
          "event_code": "xx",
          "address": "",
          "zip": null,
          "pledge": "2"
        },
        "postal_addresses": [
          {
            "address_lines": [
              null
            ],
            "postal_code": null,
            "address_status": "Verified/Not Verified",
            "primary": "True/False"
          }
        ],
        "phone_numbers": [
          {
            "number": null
          }
        ],
        "_embedded": {
          "osdi:tags": []
        },
        "_links": {
          "self": {
            "href": "http://api.opensupporter.org/api/v1/people/X"
          },
          "addresses": {
            "href": "http://api.opensupporter.org/api/v1/people/X/addresses"
          },
          "question_answers": {
            "href": "http://api.opensupporter.org/api/v1/people/X/question_answers"
          },
          "osdi-tags": {
            "href": "http://api.opensupporter.org/api/v1/people/X/tags"
          }
        }
      }

So email has been made into a custom field, so has address, etc...

Custom fields should only contain custom field data, rather than duplications of data that already exists elsewhere in the resource.

/people endpoint: ID field shouldn't exist, identifiers needs formatting

An id field is being returned, which it shouldn't be per OSDI spec. If you want to return it, you should namespace it, like civi_crm:id, but I think it's unnecessary.

Rather, you should put that ID in the identifiers array. The array should be formatted like system_prefix:[id]

So, right now you have:

"identifiers": [
    "osdi-person-[0]"
  ]

That should be:

"identifiers": [
    "civi_crm:0"
  ]

Also, note that the identifier should be a unique ID for that person on the civi system, that never changes. Since it'll be used for a link to that person.