Resource Versioning

Posted By: Tracy Mazelin on April 24, 2012

Enhanced Functionality without breaking Compatibility

We’re excited to announce a few changes coming to the API! If you have been following along with the Community Blog, you will be aware of the initiative to streamline communication values. If not take a look at the posts here and here. It follows that these changes will be reflected through the API also. As part of this effort, the "listed" functionality around each communication resource will soon be discontinued as well as the node being removed. Instead, we will be adding a new node to the people resource called "unsubscribed".

Currently, the "listed" node is returned with each communication resource as follows:

[GET] https://demo.fellowshiponeapi.com/v1/Households/1552366/Communications.json

Response:

...
"communicationType":{
"@id":"1",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/1",
"name":"Home Phone"
},
"communicationGeneralType":"Telephone",
"communicationValue":"214-759-2756",
"searchCommunicationValue":"2147592756",
"listed":"true",
"communicationComment":null,
"createdDate":"2005-01-20T01:04:55",
"lastUpdatedDate":"2005-01-20T01:04:55"
...

In 30-45 days, this node will be removed. If you are using the API to retrieve or create communication resources, you will want to make sure you are using the correct data model. It is always a good idea to call NEW before CREATE. See the Ten Commandments of API Consumption here.

The new "unsubscribed" node will be added on the people resource level for the xml or json being returned or received and this resource will be versioned.

HATEOAS

HATEOAS, is the abbreviation for Hypermedia as the Engine of Application State and it is a constraint of the REST architecture. It serves to decouple the client and server in a way that allows the server to evolve functionality without breaking compatibility. In consistency with this constraint, we are creating a new content-type so that existing users will not be impacted by this functionality enhancement. To use version two of the people resource with the new “unsubscribed” node, you will need to pass in a custom content-type:

Content-Type: application/vnd.fellowshiponeapi.com.people.people.v2+xml
or
Content-Type: application/vnd.fellowshiponeapi.com.people.people.v2+json

Example

Given:

[GET] http://demo.fellowshiponeapi.com/v1/Households/1999107/People

Content-Type: application/vnd.fellowshiponeapi.com.people.people.v2+json

Response:

"people": {
  "person": [
    {
		"@array": "true",
		"@id": "8711560",
		"@uri": "http://demo.fellowshiponeapi.com/v1/People/8711560",
		...
		"firstRecord": "2006-02-03T11:27:40",
		"lastMatchDate": null,
		"unsubscribed:" false,
		"createdDate": "2006-02-03T11:27:40",
		...

Versioning of this resource is currently live in production - give it a try!

Reduction of Communication Types

Given:

[GET] https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes

Returns a list of communication types. Following the completion of the reduction of communication types project, the following communication types will no longer be returned by the API:

For a Household:

Alternate Phone; Alternate Email; Children Phone; CR Safe Phone; Emergency Phone; Fax; Mobile; Pager; Previous Phone; School Phone; School Email;Vacation Phone; Work Phone; Work Email.

For an Individual:

Alternate Phone; Alternate Email; Children Phone; CR Safe Phone; Fax; Pager; Previous Phone; School; Phone; School Email; Vacation Phone; Work Email.

Attempting to request any of these specific CommunicationType resources in the current version will return an HTTP 404 - Not Found.

Please let us know if you have any questions and as always, thank you for being part of the Fellowship One Developer Community!

Posted In: API,