REST API v0.2.0 Nodes

Nodes

1. List Nodes
2. Get a Single Node
3. Create a New Node
4. Delete a Node

Nodes are standalone objects which represent a single question. A Node can be one of two types, AnswerableNode or NonAnswerableNode. All Nodes are answerable with the exception of the 'note' type. The type is defined by the Node's type_constraint property.

When a Survey is created, Nodes (think "question definition") are associated with it through a SurveyNode. The SurveyNode can be thought of as a specific instance of a Node -- it is the linking object between the Node and the Survey. This allows multiple Surveys to include a certain question while maintaining the ability to identify the question by a unique ID, which simplifies the aggregation of answers and makes the data easy to work with.

List Nodes

Requires Authentication

GET /api/v0/nodes

Implemented Query Parameters

Name	Type	Default	Description
offset	integer	0	The offset of the result set.
limit	integer		Limits the number of results in the result set.
type	string		Filters on the type_constraint property of the Node.
draw	integer		If included in the request, the draw parameter will be returned in the response unaltered.

Planned Query Parameters (Not Implemented)

Name	Type	Default	Description
fields	string	all fields	A comma-delimited list of node properties that should be returned.
search	string OR regex		A string or regex to search on.
regex	boolean	false	Whether or not to parse the search param as a regex.
search_fields	string	title	A comma-delimited list of node properties that should be searched.
order_by	string	created_on:DESC	A comma-delimited list of node properties with order direction, e.g. title:ASC,created_on:DESC

Note: All parameters are optional.

If there is an error, the response will contain a single error property containing the error message.

The response will consist of an object with a nodes property that contains the array of Node objects, as well as a handful of meta data properties:

limit: If a limit query arguments was supplied in the request, it is reflected in the response

offset: If a offset query arguments was supplied in the request, it is reflected in the response

(NOT YET IMPLEMENTED) total_entries: The total number of nodes before filtering

(NOT YET IMPLEMENTED) filtered_entries: The number of nodes after filtering

draw: If a draw query arguments was supplied in the request, it is reflected in the response

Example Response:

{
    "limit": 4,
    "offset": 5,
    "nodes": [
        {
            "id": "8e6e6905-3d18-4230-87ce-435fd074d421",
            "deleted": false,
            "languages": [
                "English"
            ],
            "title": {
                "English": "When did this occur?"
            },
            "hint": {
                "English": ""
            },
            "allow_multiple": false,
            "allow_other": false,
            "type_constraint": "timestamp",
            "logic": {},
            "last_update_time": "2015-07-01T18:17:18.984452+00:00"
        },
        {
            "id": "ef8edd1f-4850-41f2-9471-86189239ec64",
            "deleted": false,
            "languages": [
                "English"
            ],
            "title": {
                "English": "Exterior Photograph"
            },
            "hint": {
                "English": ""
            },
            "allow_multiple": false,
            "allow_other": false,
            "type_constraint": "photo",
            "logic": {},
            "last_update_time": "2015-07-01T18:17:18.984452+00:00"
        },
        {
            "id": "f6a2536a-3f92-4e38-84e7-f22fcba49dba",
            "deleted": false,
            "languages": [
                "English"
            ],
            "title": {
                "English": "Location"
            },
            "hint": {
                "English": ""
            },
            "allow_multiple": false,
            "allow_other": false,
            "type_constraint": "location",
            "logic": {},
            "last_update_time": "2015-07-01T18:17:18.984452+00:00"
        },
        {
            "id": "f81085ad-9e60-4128-ac53-aa3ac2f88fa7",
            "deleted": false,
            "languages": [
                "English"
            ],
            "title": {
                "English": "Patient Birthdate"
            },
            "hint": {
                "English": ""
            },
            "allow_multiple": false,
            "allow_other": false,
            "type_constraint": "date",
            "logic": {},
            "last_update_time": "2015-07-01T18:17:18.984452+00:00"
        }
    ]
}

Get a Single Node

Requires Authentication

/api/v0/nodes/<Node_UUID>

Example Response:

{
    "id": "8e6e6905-3d18-4230-87ce-435fd074d421",
    "deleted": false,
    "languages": [
        "English"
    ],
    "title": {
        "English": "When did this occur?"
    },
    "hint": {
        "English": ""
    },
    "allow_multiple": false,
    "allow_other": false,
    "type_constraint": "timestamp",
    "logic": {},
    "last_update_time": "2015-07-01T18:17:18.984452+00:00"
}

Create a New Node

Requires Authentication

POST /api/v0/nodes

A Node (again, think 'question') can be one of several types, defined by its type_constraint value, which enforces the types of acceptable answer values:

NODE_TYPES = {
    'text': TextQuestion,
    'photo': PhotoQuestion,
    'integer': IntegerQuestion,
    'decimal': DecimalQuestion,
    'date': DateQuestion,
    'time': TimeQuestion,
    'timestamp': TimestampQuestion,
    'location': LocationQuestion,
    'facility': FacilityQuestion,
    'multiple_choice': MultipleChoiceQuestion,
    'note': Note,
}

The allow_multiple property defines whether this Node (question) should accept multiple answers. Defaults to false.

The allow_other property defines whether this Node (question) should allow an 'other' answer option. Defaults to false.

Example Request Body:

{
    "title": {
        "English": "text_node"
    },
    "hint": {
        "English": "Some test hint."
    },
    "type_constraint": "text",
    "logic": {},
}

Example Response:

{
    "id": "d1091c27-ae98-4272-957f-f28c236fc832",
    "deleted": false,
    "languages": [
        "English"
    ],
    "title": {
        "English": "text_node"
    },
    "hint": {
        "English": "Some test hint."
    },
    "allow_multiple": false,
    "allow_other": false,
    "type_constraint": "text",
    "logic": {},
    "last_update_time": "2015-07-01T20:22:37.461764+00:00"
}

Multiple Choice nodes have a choices property:

Example Request Body (multiple_choice type)

{
    "title": {"English": "Which food is the tastiest?"},
    "hint": {
        "English": "Some test hint."
    },
    "allow_other": true,
    "type_constraint": "multiple_choice",
    "logic": {},
    "choices": [
        {
            "choice_text": {
                "English": "Bagel"
            }
        },
        {
            "choice_text": {
                "English": "Burger"
            }
        }
    ]
}

Example Response:

{
    "id": "233616eb-d923-4b83-87af-620f011c4d34",
    "deleted": false,
    "title": {
        "English": "Which food is the tastiest?"
    },
    "hint": {
        "English": "Some test hint."
    },
    "choices": [
        {
            "choice_id": "d06ac0fb-0281-4ed4-8729-e79c08d6c8aa",
            "choice_text": {
                "English": "Bagel"
            }
        },
        {
            "choice_id": "7b66b5da-0fce-4dfd-8a65-d9fd67b69130",
            "choice_text": {
                "English": "Burger"
            }
        }
    ],
    "allow_multiple": false,
    "allow_other": true,
    "type_constraint": "multiple_choice",
    "logic": {},
    "last_update_time": "2015-07-01T20:38:43.660554+00:00"
}

Delete Node

Requires Authentication

DELETE /api/v0/nodes/<Node_UUID>

Delete requests have no response payload. A successful deletion will respond with an empty 204 No Content status code.

Note: Deletions are non-destructive; data is simply marked as deleted, and will no longer appear in standard queries.