Dartmouth API Developer Portal

Data Types, Formats and Naming Standards

This document specifies the format and data types that will be used for JSON input and output payloads.

JSON Payload Format Note: The examples below are in “pretty” format for readability. In practice, JSON payloads will be minified (i.e. no spaces, tabs, or linefeeds).

Payload for a single object will be a JSON object, for example:

{
  "netid": "f00089b",
  "email_address": "robert.a.zimmerman@dartmouth.edu",
  "full_name": "Robert A. Zimmerman",
  "first_name": "Robert",
  "last_name": "Zimmerman",
  "legal_name": "Robert A. Zimmerman",
  "personal_phone": "603-555-2525"
}

Payload for multiple objects will be an array of JSON objects, for example:

[{
  "netid": "f00089b",
  "email_address": "robert.a.zimmerman@dartmouth.edu",
  "full_name": "Robert A. Zimmerman",
  "first_name": "Robert",
  "last_name": "Zimmerman",
  "legal_name": "Robert A. Zimmerman",
  "personal_phone": "603-555-2525"
},
{
  "netid": "f00089c",
  "email_address": "robert.a.zimmerman.jr@dartmouth.edu",
  "full_name": "Robert A. Zimmerman Jr.",
  "first_name": "Robert",
  "last_name": "Zimmerman Jr.",
  "legal_name": "Robert A. Zimmerman Jr.",
  "personal_phone": "603-555-2526"
}]

An empty array is an acceptable payload to represent no objects (e.g. as the result of a search that returns no items), for example:

[]

For unsuccessful requests (anything that results in a http status code other than 200), a single JSON object with a message attribute (at least, other attributes can be added as needed) will be returned, for example:

{
  "message": "Not authorized"
}

JSON Attribute Name Format

For attribute names, snake_case (all lowercase with underscore separators) will be used:

netid first_name last_name end_date is_campus_resident Note: There is one exception to this: the “content-type” attribute for hypermedia (see below).

All date attribute names will have a '_date" suffix, for example:

end_date

All boolean attribute names will be preceded by 'is_', for example:

is_campus_resident

Resources that aggregate data from multiple sources will include the following attribute that contains a collection of the sources (see details below under Custom Data Types): data_sources

JSON Attribute Value Data Types

Standard Data Types

Below was copied from https://www.w3schools.com/js/js_json_datatypes.asp In JSON, values must be one of the following data types:

a string a number an object (JSON object) an array a boolean null

JSON values cannot be one of the following data types:

a function a date undefined Shape JSON Strings

Strings in JSON must be written in double quotes.

Example

{ "name":"John" }

JSON Numbers

Numbers in JSON must be an integer or a floating point. Example

{ "age":30 }

NOTE: Value MUST be all numeric (0-9) with one optional decimal point and optional dash prefix to indicate negative numbers. Valid examples:

3000 30.12345 -30.5 Invalid examples: 3,000 30,12345 30.1234.5 (30.5) $30.50

JSON Objects

Values in JSON can be objects. Example

{
"employee":{ "name":"John", "age":30, "city":"New York" }
}

Objects as values in JSON must follow the same rules as JSON objects.

JSON Arrays

Values in JSON can be arrays. Example

{
"employees":[ "John", "Anna", "Peter" ]
"employee_ids":[ 200001, 200002, 200003]
}

JSON Booleans

Values in JSON can be true/false.

Example

{ "sale":true }

JSON null

Values in JSON can be null. Example json { "middlename":null }

Above was copied from https://www.w3schools.com/js/js_json_datatypes.asp

Custom Data Types

Dartmouth will support the following custom data types:

Date String Hypermedia Object Details follow. Date String

For all date attribute names, add “_date” suffix, for example:

creation_date end_date birth_date

Date values will use the JSON string data type that represents the date’s UTC value in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) for example:

{ "start_date":"2012-04-23T18:25:43Z" }

Note: Z above indicates date value is Coordinated Universal Time (UTC) which is the primary time standard by which the world regulates clocks and time. It is within about 1 second of mean solar time at 0° longitude; it does not observe daylight saving time. For most purposes, UTC is considered interchangeable with Greenwich Mean Time (GMT), but GMT is no longer precisely defined by the scientific community.

Converting Date to ISO8601/UTC String

PLSQL

select to_char((from_tz(to_timestamp(to_char(sysdate, 'YYYY-MM-DD HH:MI:SS PM'), 'YYYY-MM-DD HH:MI:SS PM') ,'US/Eastern') at time zone 'UTC'),'YYYY-MM-DD"T"HH24:MI:SS"Z"') utc_iso8601
from dual;

PostGres

select to_char (now()::timestamp at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') utc_iso8601;

Ruby

Time.now.utc.iso8601

JavaScript

var d = new Date();
var s = d.toISOString();

Converting ISO8601/UTC String to Date

PLSQL

select cast (from_tz (to_timestamp(replace(replace('2013-11-06T15:22:19Z', 'T', ' '), 'Z', ''), 'YYYY-mm-dd hh24:mi:ss'), 'GMT') at time zone 'US/Eastern' as date) local_date
from dual;

PostGres

select to_timestamp('2013-11-06T15:22:19Z', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') at time zone 'US/Eastern' local_date;

Ruby

Time.now.in_time_zone("Eastern Time (US & Canada)")
Time.now.in_time_zone("UTC")

JavaScript

var d = new Date('2013-11-06T15:22:19Z');

Hypermedia Object

For all hypermedia attribute names, add “_link” suffix, for example:

photo_link name_audio_link

The JSON object representing hypermedia can contain the following attributes:

link (required) content-type (optional)

Note: content-type is the one exception to the snake_case rule for attribute names size (optional)

Examples: json "jpg_photo_link" : { "link" : "https://api.dartmouth.edu/api/people/d35022g/photo", "content-type" : "image/jpeg", "size" : 32649 }, "base64_photo_link" : { "link" : "https://api.dartmouth.edu/api/people/d35022g/photo?base64=1", "content-type" : "text/plain", "size" : 67890 }

data_sources

For APIs that aggregate data from multiple sources, a data_sources object/collection will be included in the payload containing the following attributes:

name link cache_date update_date

Note: We considered included a description attribute, but decided it was not appropriate here, we will document descriptions for each resource name.

Example: json "data_sources" : [{ "name" : "sis", "link" : "https://api.dartmouth.edu/api/people/d35022g?data_source=sis", "update_date": "2012-04-23T18:25:43.511Z", "cache_date":"2012-04-23T18:25:43.511Z"}, {"name" : "hrs", "link" : "https://api.dartmouth.edu/api/people/d35022g?data_source=hrs", "update_date": "2012-04-23T18:25:43.511Z", "cache_date":"2012-04-23T18:25:43.511Z"}]

Representing Null/Empty Values

Every attribute specified for a resource GET endpoint will always be included in its payload; when an attribute is missing, empty, or unavailable for a particular resource record, that attribute will be included in the payload. So the payload for a particular resource GET endpoint will always contain the same set of attributes.

JSON Data Type

Null/Empty Value Comments String "" or null Use value produced by the source system (e.g. Oracle will always use null for empty strings, other systems may use "" for empty strings). Number null

Object

{} or null

Array

[] Null is not supported for arrays, must use [] Boolean null