Store
To store data through the nodegoat API you need a valid domain, a valid path, and use user authentication. The data you submit has to be formatted in JSON.
Storing data in nodegoat will start a new transaction: the transaction will be committed when all data is successfully processed, or rolled back when an error occurs. When storing Object data, a new transaction runs for every 1000 Objects. In case of an error, a message is included that specifies the ID of the last processed Object.
Example: The following URL contains the possible basic domain and path parameters to store data to an Object:
Access Project 1, access Project’s data, Type 2, target Object 3, overwrite the Object with the provided JSON-formatted Object data
PUT https://nodegoat.io/project/1/data/type/2/object/3 '{"object": {"object_name_plain": "A Node in nodegoat"},"object_definitions": {"1": {"object_description_id": 1,"object_definition_ref_object_id": null,"object_definition_value": "Hello"}}}'
Access Project 1, access Project’s Filters, target Filter 2, change the Filter's name
PATCH https://nodegoat.io/project/1/feature/filter/2 '{"name": "Sent from Paris"}'
Domain
Since you are making an authenticated request, HTTPS is required and should query nodegoat’s main API domain at nodegoat.io or api.nodegoat.net.
Path
The path tells the API what mode and data you want to target, either Object data or Type templates.
//nodegoat/A
Specify which nodegoat Project to access. Optional.
Only applicable when storing data to Objects (mode = data) or the Project's Filters, Scopes, and Conditions (mode = feature), see the next section on mode.
Since the data Model transcends the Projects within a nodegoat Domain, no project should be specified when storing data to the data Model (mode = model). The user has to have administrator clearance to be be able change the data Model.
| A | Description |
|---|---|
/ project / ID | mode = data and mode = feature only. Access a specific nodegoat Project. If this is left out, the default configured Project is assumed. |
//nodegoat/A/B
Specify the mode.
| B | Description |
|---|---|
/ data | Access the Project’s data. |
/ model | Access the Project's data Model. Requires administrator clearance. |
/ feature | Access the Project's Filters, Scopes, and Conditions. These use the data Model, but are not part of it. Requires the clearance to interact with the Project's data. |
//nodegoat/A/B:data/C
Specify for which Type you want to change the data.
| C | Description |
|---|---|
/ type / ID | Access data for the specified Type. |
//nodegoat/A/B:data/C/D
Apply Project- and Type-specific operations to the request. You can either target an Object in the path, or specify it in the data you submit. Optional.
| D | Description |
|---|---|
/ object / ID | Target the specified Object. |
//nodegoat/B:model/C
Specify for which Type you want to change the template. You can either target a Type in the path, or specify it in the data you submit. Optional.
| C | Description |
|---|---|
/ type / ID | Access data for the specified Type. |
//nodegoat/A/B:feature/C
Specify which Project feature you want to change. One of the following parameters has to be provided.
| C | Description |
|---|---|
/ filter | Access the Project's Filters. |
/ scope | Access the Project's Scopes. |
/ condition | Access the Project's Conditions. |
//nodegoat/A/B:feature/C/D
Target a stored feature. You can either target a feature in the path, or specify it in the data you submit. Optional.
| D | Description |
|---|---|
/ ID | Target the specified Filter, Scope, or Condition. The methods PUT and PATCH target one feature at a time, to write to more than one in a single request you key them by ID in the data you submit. The method DELETE does accept more than one: / ID(,ID). |
Component
The option component allows you to further specify your request by means of option parameters.
//nodegoat/A/B:data/C/D?O
All parameters in the option component are optional.
| O | Description |
|---|---|
versioning = 1 orversioning = 0 | Disable or enable version management. Versioning is enabled by default. When disabled all data will be stored directly towards the same version-state. When updating data, this will then not check whether a value really needs to be updated and what the changes are, it will always overwrite the existing value with the one you provide. This is an advanced feature and should be used accordingly. |
Method
The request method allows you to specify the operation you want to perform for Object data in data mode, Type templates in data Model mode, or the Project's Filters, Scopes, and Conditions in feature mode.
Data
Each method allows you to submit nodegoat Object dictionaries that are structured using the Query Model response and formatted following the Query Data response:
OBJECT = {
"object": {
"object_name_plain": "A Node in nodegoat",
},
"object_definitions": [
{
"object_description_id": 1,
"object_definition_ref_object_id": null,
"object_definition_value": "Hello"
}
],
"object_subs": [
{
"object_sub": {
"object_sub_id": null,
"object_sub_details_id": 3,
"object_sub_date_start": 17680101,
"object_sub_date_end": 17680101,
"object_sub_location_ref_object_id": 4,
"object_sub_location_ref_type_id": 5,
"object_sub_location_ref_object_sub_details_id": 6,
"object_sub_location_type": "reference",
},
"object_sub_definitions": [
{
"object_sub_description_id": 7,
"object_sub_definition_ref_object_id": null,
"object_sub_definition_value": "Great Place"
}
]
}
]
}PUT
When submitting data with the PUT method, you can overwrite the Object specified in the path, overwrite the Objects specified in the submitted data, or create new Objects.
To overwrite an Object specified in the path https://nodegoat.io/project/1/data/type/2/object/3, you submit a single Object dictionary:
OBJECTTo overwrite Objects specified in the submitted data, you access the path without an Object ID https://nodegoat.io/project/1/data/type/2/object/, create the key update, and provide a dictionary with Object IDs as keys and Object dictionaries as values:
{
"update": {
"3": OBJECT,
"333": ...
}
}To add new Objects to a Type, you access the path without an Object ID https://nodegoat.io/project/1/data/type/2/object/, create the key add, and submit a list with Object dictionaries:
{
"add": [
OBJECT,
...
]
}To both add and update Objects in a single request, you access the path without an Object ID https://nodegoat.io/project/1/data/type/2/object/ and provide the key add with a list and the key update with a dictionary:
{
"add": [OBJECT, ...],
"update": {"3": OBJECT, "333": ...}
}PATCH
When submitting data with the PATCH method, you can update the Object specified in the path or update the Objects specified in the data. Any Object Description/Sub-Object/Sub-Object Description that is not specified in the submitted data will not be touched. For instance, this allows you to update specific Object Descriptions and append new Sub-Objects.
To update an Object specified in the path https://nodegoat.io/project/1/data/type/2/object/3, you submit a single Object dictionary that only contains the data you want to update:
OBJECTTo update Objects specified in the submitted data, you access the path without an Object ID https://nodegoat.io/project/1/data/type/2/object/ and provide a dictionary with Object IDs as keys and Object dictionaries as values:
{
"3": OBJECT,
"333": ...
}DELETE
To delete Objects, you either apply the method DELETE to the path to a specific Object, e.g. https://nodegoat.io/project/1/data/type/2/object/3 and submit a body containing true, or you access the path without an Object ID and submit a dictionary with the Object IDs as keys:
{
"3": true,
"333": true
}Model
Each method allows you to submit nodegoat Type template dictionaries that are formatted following the Query Model response. nodegoat Type templates can be dynamic: it is possible to use names as IDs instead of the numeric IDs within Type templates (e.g. whenever the template references other Type templates like object_description_ref_type_id or object_sub_details_location_ref_object_sub_details_id), see the output when using parameter output = 'template'. By using name IDs instead of numeric IDs, you are able to store a whole nodegoat data Model in one go.
TYPE = {
"type": {
"id": "Person",
"class": 0,
"name": "Person",
"color": "#ff00ff",
"use_object_name": false,
"object_name_in_overview": true
},
"object_descriptions": [
{
"object_description_id": "Second Name",
"object_description_name": "Second Name",
"object_description_value_type_base": "",
"object_description_value_type_settings": "",
"object_description_is_unique": false,
"object_description_is_identifier": false,
"object_description_has_multi": false,
"object_description_ref_type_id": null,
"object_description_in_name": true,
"object_description_in_search": true,
"object_description_in_overview": true,
"object_description_clearance_view": 0,
"object_description_clearance_edit": 0
}
],
"object_sub_details": [
{
"object_sub_details": {
"object_sub_details_id": "Birth",
"object_sub_details_name": "Birth",
"object_sub_details_is_single": true,
"object_sub_details_is_required": true,
"object_sub_details_is_date_period": false,
"object_sub_details_date_use_object_sub_details_id": null,
"object_sub_details_date_use_object_sub_description_id": null,
"object_sub_details_date_use_object_description_id": null,
"object_sub_details_location_ref_only": false,
"object_sub_details_location_ref_type_id": "City",
"object_sub_details_location_ref_type_id_locked": false,
"object_sub_details_location_ref_object_sub_details_id": "Located",
"object_sub_details_location_ref_object_sub_details_id_locked": false,
"object_sub_details_location_use_object_sub_details_id": null,
"object_sub_details_location_use_object_sub_description_id": null,
"object_sub_details_location_use_object_description_id": null,
"object_sub_details_location_use_object_id": false,
"object_sub_details_clearance_view": 0,
"object_sub_details_clearance_edit": 0
},
"object_sub_descriptions": [
{
"object_sub_description_id": "Notes",
"object_sub_description_name": "Notes",
"object_sub_description_value_type_base": "text_tags",
"object_sub_description_value_type_settings": "",
"object_sub_description_ref_type_id": null,
"object_sub_description_use_object_description_id": null,
"object_sub_description_in_overview": true,
"object_sub_description_clearance_view": 4,
"object_sub_description_clearance_edit": 4
}
]
}
]
}PUT
When submitting Type templates with the PUT method, you can overwrite the Type specified in the path, overwrite the Types specified in the submitted data, or create new Types.
To overwrite a Type specified in the path https://nodegoat.io/model/type/1/, you submit a single Type template dictionary:
TYPETo overwrite Types specified in the submitted data, you access the path without a Type ID https://nodegoat.io/model/type/, create the key update, and provide a dictionary with Type IDs (or Type names) as keys and Type template dictionaries as values:
{
"update": {
"Person": TYPE,
"3": ...
}
}To add new Types, you access the path without a Type ID https://nodegoat.io/model/type/, create the key add, and submit a list with Type template dictionaries:
{
"add": [
TYPE,
...
]
}To both add and update Types in a single request, you access the path without a Type ID https://nodegoat.io/model/type/ and provide the key add with a list and the key update with a dictionary:
{
"add": [TYPE, ...],
"update": {"Person": TYPE, "3": ...}
}PATCH
When submitting data with the PATCH method, you can update the Type specified in the path or update the Types specified in the data. Any Object Description/Sub-Object/Sub-Object Description that is not specified in the submitted data will not be touched. For instance, this allows you to create or change specific Object Descriptions and configure new Sub-Objects.
To remove an Object Description/Sub-Object/Sub-Object Description from the Type, provide their respective ID (or name as ID), and set their name (e.g. object_description_name) to empty or null.
To update a Type specified in the path https://nodegoat.io/model/type/1/, you submit a single Type template dictionary that only contains the data you want to update:
TYPETo update Types specified in the submitted data, you access the path without a Type ID https://nodegoat.io/model/type/ and provide a dictionary with Type IDs (or Type names) as keys and Type template dictionaries as values:
{
"Person": TYPE,
"3": ...
}DELETE
A Type that is shared from another nodegoat Domain, and a system Type, cannot be deleted. Such a Type is refused, and no Type in the same request is deleted.
To delete Types, you either apply the method DELETE to the path to a specific Type, e.g. https://nodegoat.io/model/type/1/ and submit a body containing true, or you access the path without a Type ID and submit a dictionary with the Type IDs (or Type names) as keys:
{
"Person": true,
"3": true
}Feature
Each method allows you to submit Filter, Scope, and Condition dictionaries that are structured following the Query feature response.
FEATURE = {
"type_id": 2,
"name": "Sent from Paris",
"description": "Selects the Letters that were sent from Paris.",
"usage": "personal",
"form": FORM
}| Member | Description |
|---|---|
type_id | The Type the feature belongs to. Required when adding a feature. The Type of a stored feature cannot be changed. |
name | The name the feature is stored under. |
description | What the feature does, for whoever selects it from the Project's stored features. Optional. |
usage | Who the feature is stored for: personal for the storing user alone, project for everyone in the Project, or admin for all Projects. personal when it is left out. The usage admin requires administrator clearance, and is not available to a Scope. The usage of a stored feature cannot be changed. Optional. |
form | The Filter, Scope, or Condition itself, in the same form that is returned when you access / feature / filter, / feature / scope, or / feature / condition. Access those for how the form is composed, and for the Project's stored forms as examples that can be copied and adjusted. |
model_conditions | Condition only. The Conditions that are applied to the other Types a query touches on, with the Type IDs as keys and a condition_id or condition_use_current as value. Only a stored Condition carries these: a Condition that is passed to a query as a form applies to the queried Type only. Optional. |
A feature that belongs to another user cannot be changed, and neither can one that nodegoat maintains by 'auto-store'. Because the Type and the usage of a stored feature cannot be changed either, a request that submits a different one is refused.
The submitted form is checked against the data Model before it is stored. When the form refers to an Object Description, a Sub-Object Details, a Sub-Object Description, or a Type that does not exist, or when it holds an instruction that does nothing, the request is refused with a message that names what was found.
PUT
When submitting features with the PUT method, you can overwrite the feature specified in the path, overwrite the features specified in the submitted data, or create new features.
To overwrite a Filter specified in the path https://nodegoat.io/project/1/feature/filter/2, you submit a single feature dictionary:
FEATURETo overwrite features specified in the submitted data, you access the path without an ID https://nodegoat.io/project/1/feature/filter/, create the key update, and provide a dictionary with the feature IDs as keys and feature dictionaries as values:
{
"update": {
"2": FEATURE,
"22": ...
}
}To add new features, you access the path without an ID https://nodegoat.io/project/1/feature/filter/, create the key add, and submit a list with feature dictionaries:
{
"add": [
FEATURE,
...
]
}To both add and update features in a single request, you access the path without an ID https://nodegoat.io/project/1/feature/filter/ and provide the key add with a list and the key update with a dictionary:
{
"add": [FEATURE, ...],
"update": {"2": FEATURE, "22": ...}
}PATCH
When submitting features with the PATCH method, you can update the feature specified in the path or update the features specified in the data. Any member that is not specified in the submitted data keeps its stored value. For instance, this allows you to change a feature's name without submitting its form again.
To update a Filter specified in the path https://nodegoat.io/project/1/feature/filter/2, you submit a single feature dictionary that only contains the data you want to update:
FEATURETo update features specified in the submitted data, you access the path without an ID https://nodegoat.io/project/1/feature/filter/ and provide a dictionary with the feature IDs as keys and feature dictionaries as values:
{
"2": FEATURE,
"22": ...
}DELETE
To delete features, you either apply the method DELETE to the path to specific features, e.g. https://nodegoat.io/project/1/feature/filter/2,22 and submit no body, or you access the path without an ID and submit a dictionary with the feature IDs as keys:
{
"2": true,
"22": true
}Response
The result from your submission to the nodegoat API can be found in the JSON response under the key data. A list will be returned with the Type, Object, or feature IDs that have been added, updated, or deleted.