How to get started using the REST API

Posted By: Jas Singh

What’s the process of getting onto using the REST API?

First of all, a request is submitted for a Key.

Applications developed using the REST API are divided into 3 categories: 1st party, 2nd party and 3rd party applications. 1st Party applications are written and made public by Fellowship Technologies. 2nd Party applications are written and made private by the Consumer and used by the Consumer’s (or Tenant’s) Users - They will be marked as Private. 3rd Party Consumer Applications are written and made public for consumption across Tenants. They will be marked as Public.

When the request is submitted, it goes through an approval process at Fellowship Technologies. If the request is approved, a Consumer Key and Secret is provided for the consumer application to use.

To begin accessing data using the API, the consumer application has to obtain an Access Token and Secret. You can read all about the consumer application authentication process here

There is a PHP OAuth library made publicly available by Fellowship Technologies. You can read my blog post and download the code library.

If you are a 2nd party application, please read the related blog post.

After you have read the blog posts, you should feel comfortable with getting your hands at the Access Token and Secret. Access Token and Secret are required to access data from Fellowship One REST API.

Below, I am going to show an example of how you can use the REST API to create a household, and a person in that household. I am going to assume that you are familiar with the PHP programming language.

First of all let me go through some classes created to hold the data to be passed around functions.

A Person class contains all the data points required to create a person, and looks like

class Person {
public $id;
public $imageURI;
public $iCode;
public $title;
public $salutation;
public $prefix;
public $firstName;
public $lastName;
......
......
}

On the same note, a Communication class holds all the data points required to carry a Communication value (Email, Phone etc)

class Communication {
public $communicationId;
public $householdID ;
public $individualID;
public $communicationTypeID;
public $communicationTypeName;
public $communicationGeneralType;
public $communicationValue;
.........
.........
}

Next comes the code to create a household, followed by creating a person in that household

// Step A: Create an instance of OAuthClient class
// (available with the PHP OAuth library download)

$postContentType = array(
              "Accept: application/json",
              "Content-type: application/json");
$getContentType = array("Accept: application/json");
$apiConsumer = new OAuthClient(
                   AppConfig::$base_url,
                   AppConfig::$consumer_key,
                   AppConfig::$consumer_secret);
$this->baseUrl = $ apiConsumer->getBaseUrl();
$apiConsumer->initAccessToken($accessToken,
                          $tokenSecret);

// Step B: Create a new Household
// Create a new Household

$householdFirstName = ‘john’;.
$householdLastName = ‘doe’;
$householdName = $householdFirstName
         .' '.$householdLastName;
$requestBody =
"{"household":{"@id":"","@uri":"","@oldID":"",
"@hCode":"","householdName":"$householdName",
"householdSortName":"$householdLastName",
"householdFirstName":"$householdFirstName",
"lastSecurityAuthorization":null,
"lastActivityDate":null,"createdDate":null,
"lastUpdatedDate":null}}";

$requestUrl =
 $this->baseUrl.AppConfig::$f1_household_create;
$householdId = $apiConsumer->postRequest(
                         $requestUrl,
                         $requestBody,
                         $this->postContentType);

// Step C: Create a person in the Household

// Create a person object
$person = new Person();
$person->firstName = $firstName;
$person->lastName = $lastName;
$person->gender = 'Male';
$person->householdMemberTypeId =$householdMemberTypeId;
$person->status = $statusId;
$person->householdId = $householdId;
$person->maritalStatus = "Married";
$person_id = $this->addPerson($person);

// addPerson method is defined as follows

public function addPerson($person) {
$requestBody =
"{"person":{"@id":"","@uri":"","@oldID":"","@iCode":"",
"@householdID":"$person->householdId",
"@oldHouseholdID":"","title":"$person->title",
"salutation":"$person->salutation",
"prefix":"$person->prefix",
"firstName":"$person->firstName",
"lastName":"$person->lastName",
"suffix":"$person->suffix",
"middleName":"$person->middleName",
"goesByName":"$person->goesByName",
"formerName":"$person->formerChurch",
"gender":"$person->gender",
"dateOfBirth":"$person->dateOfBirth",
"maritalStatus":"$person->maritalStatus",
"householdMemberType":{
"@id":"$person->householdMemberTypeId",
"@uri":"",
"name":"Head"},
"isAuthorized":"true",
"status":{
"@id":"$person->status",
"@uri":"","name":null,
"comment":null,
"date":null,
"subStatus":{
 "@id":"$person->subStatus",
 "@uri":"","name":null
 }},
"occupation":{
"@id":"$person->occupation",
"@uri":"","name":null,
"description":null},
"employer":"$person->employer",
"school":{
"@id":"$person->school",
"@uri":"","name":null},
"denomination":{
"@id":"$person->denomination",
"@uri":"","name":null},
"formerChurch":"$person->formerChurch",
"barCode":"$person->barCode",
"memberEnvelopeCode":"$person->memberEnvelopeCode",
"defaultTagComment":"$person->defaultTagComment",
"weblink":{
"userID":"$person->weblinkUserID",
"passwordHint":"$person->passwordHint",
"passwordAnswer":"$person->passwordAnswer"},
"solicit":"$person->solicit",
"thank":"$person->thank",
"firstRecord":null,"lastMatchDate":null,
"createdDate":null,"lastUpdatedDate":null}}";

$requestUrl =
       $this->baseUrl.AppConfig::$f1_people_create;
$result = $apiConsumer->postRequest(
                   $requestUrl,
                   $requestBody,
                   $this->postContentType);
$json_string = json_decode($result, true);
$person_id =  $json_string["person"]["@id"];
return $person_id;
}

// Step D: Add email

$comm = new Communication();
$comm->communicationTypeID = 4; // Email
$comm->communicationValue = "testuser@myChurch.com";
$comm->individualID = $person_id
$this->addCommunication($comm);

// addCommunication method is defined as

public function addCommunication($communication) {
$requestBody = "
{"communication": {
 "@id": "",
 "@uri": "",
 "household": {
 "@id": "$communication->householdID",
 "@uri": ""},
"person": {
 "@id": "$communication->individualID",
 "@uri": ""},
"communicationType": {
 "@id": "$communication->communicationTypeID",
 "@uri": "",
 "name": null},
"communicationGeneralType": null,
"communicationValue": "$communication->communicationValue",
"searchCommunicationValue": null,
"listed": "true",
"communicationComment": null,
"createdDate": null,
"lastUpdatedDate": null
}}";
$requestUrl =
   $this->baseUrl.AppConfig::$f1_people_communications;
$requestUrl = str_replace(
               "{id}",
               $communication->individualID,
               $requestUrl);
return $this->apiConsumer->postRequest($requestUrl,
$requestBody, $this->postContentType);
}

Posted In: API, Tips,

Comments:
No one has commented yet. Be the first!
Commenting is not available in this channel entry.

Categories:

Previous Posts:


Subscribe to the RSS feed!