API Update: Custom Fields

160 views

Skip to first unread message

CATS API v3

unread,

Sep 3, 2015, 11:58:07 AM9/3/15

to CATS API v3

A new update has been released for CATS API v3. The primary focus of this update is custom fields. It adds a list of custom fields available to a site, as well as the ability to retrieve and update custom fields that belong to a candidate, company, contact, or job.

It also introduces an updated data structure for collections of resources to assist with uniformity across the API. The specification, known as HAL, will allow for retrieving resources with linked and embedded resources to assist with traversing data. This change only causes backwards incompatibility with collections and not individual resources.

Old structure:

{
  "id": 3,
  "first_name": "Joel",
  "middle_name": null,
  "last_name": "Larson",
  "title": "Developer",
  "email_address": "jo...@catsone.com",
  "secondary_email_address": null,
  "address": {
    "street": null,
    "city_name": null,
    "state_name": null,
    "postal_code": null
  },
  "social_media_urls": [],
  "website": "http://www.catsone.com/",
  "home_phone": null,
  "cell_phone": null,
  "work_phone": null,
  "best_time_to_call": null,
  "current_employer": "CATS Software Inc.",
  "date_available": null,  "current_pay": null,  "desired_pay": null,  "is_willing_to_relocate": false,
  "key_skills": null,
  "notes": null,
  "is_hot": true,
  "contact_id": null,
  "owner_id": 1,
  "entered_by": "API User",
  "date_created": "2015-09-02T22:55:55+0000",
  "date_modified": "2015-09-02T23:19:26+0000",
}

New Structure:

{
  "id": 3,
  "first_name": "Joel",
  "middle_name": null,
  "last_name": "Larson",
  "title": "Developer",
  "email_address": "jo...@catsone.com",
  "secondary_email_address": null,
  "address": {
    "street": null,
    "city_name": null,
    "state_name": null,
    "postal_code": null
  },
  "social_media_urls": [],
  "website": "http://www.catsone.com/",
  "home_phone": null,
  "cell_phone": null,
  "work_phone": null,
  "best_time_to_call": null,
  "current_employer": "CATS Software Inc.",
  "date_available": null,  "current_pay": null,  "desired_pay": null,  "is_willing_to_relocate": false,
  "key_skills": null,
  "notes": null,
  "is_hot": true,
  "contact_id": null,
  "owner_id": 1,
  "entered_by": "API User",
  "date_created": "2015-09-02T22:55:55+0000",
  "date_modified": "2015-09-02T23:19:26+0000",
     "_links": {
    "self": {
      "href": "/candidates/3"
    },
    "custom_fields": {
      "href": "/candidates/3/custom_fields"
    },
    "owner": {
      "href": "/users/1"
    }
  },
  "_embedded": {
    "custom_fields": [
      {
        "id": 1,
        "value": null,
        "_links": {
          "self": {
            "href": "/candidates/3/custom_fields/1"
          },
          "definition": {
            "href": "/custom_fields/1"
          }
        },
        "_embedded": {
          "definition": {
            "id": 1,
            "dataItemType": "candidate",
            "name": "Example #1",
            "comment": "Comment #1",
            "field": {
              "name": "text"
            },
            "_links": {
              "self": {
                "href": "/custom_fields/1"
              }
            }
          }
        }
      }
    ]
  }
}

The "_links" property is designed to be similar to anchors in an HTML page. The "_embedded" property is designed as a cache for linked resources to reduce the amount of requests.