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"}'
Access the Projects, target Project 1, change the Project's name
PATCH https://nodegoat.io/project/1 '{"name": "Letters Collected"}'
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 Project to access and what you want to store for Object data, data Model, the Project's features like Filters, Scopes, and Conditions, or the Projects themselves.
//nodegoat/A
Specify which nodegoat Project to access. Optional.
| A | Description |
|---|---|
none | Access the default nodegoat Project for mode = data and mode = feature. For mode = model there is none Project specificity in the path, see the next section on mode. |
/ project / ID | Access a specific nodegoat Project by its ID. mode = data and mode = feature only. |
/ project or/ project / ID without a mode | Access the Projects' configuration. See Project. Requires administrator clearance. |
//nodegoat/A.openapi
The .openapi and .mcp described in Query include the store operations: / project / ID .openapi those of the selected Project, / project / .openapi those of the Projects' own configuration.
//nodegoat/A/B
Specify the mode.
| B | Description |
|---|---|
/ data | Access the Project’s data. |
/ model | Access the full data Model of the nodegoat Domain. For storing, the data Model transcends Projects within a nodegoat Domain. 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 Model mode, the Project's Filters, Scopes, and Conditions in feature mode, or the Projects themselves.
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 includes 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 contains 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
}Project
Each method allows you to submit Project dictionaries that are structured following the Query Project response. The project_id of the response is not submitted: a Project is targeted by the path, or by its ID as key in the submitted data.
PROJECT = {
"name": "Letters Collected",
"form": {
"full_scope_enable": true,
"source_referencing_enable": true,
"discussion_enable": false,
"system_date_cycle_enable": false,
"system_ingestion_enable": false,
"system_reconciliation_enable": false,
"visual_settings_id": null,
"types": [
{
"type_id": 2,
"color": "#ff00ff",
"type_information": "",
"type_edit": "create",
"type_filter_id": null,
"type_filter_object_subs": false,
"type_condition_id": null,
"type_context_id": null,
"type_frame_id": null,
"configuration_exclude": false,
"configuration": {
"object_descriptions": {
"1": {"edit": true, "view": true}
}
}
}
],
"date_types": [],
"location_types": [],
"source_types": [2],
"use_projects": [1]
}
}| Member | Description |
|---|---|
name | The name of the Project. Required when adding or overwriting a Project. |
form | The Project itself, in the same form that is returned when you access / project with administrator clearance, see the members below. Required when adding or overwriting a Project. |
The form contains the following members. The IDs of stored features (Filters, Conditions, Contexts, Frames, Visual Settings) are those of the Project, or of a Project in use_projects. An ID that is not set is null.
| Member | Description |
|---|---|
full_scope_enable | Traverse all Types of the nodegoat Domain, not only those of the Project. |
source_referencing_enable | Data can cite sources. |
discussion_enable | Objects have a discussion. |
system_date_cycle_enable,system_ingestion_enable,system_reconciliation_enable | Include the system Type for date cycles, Ingestion, or Reconciliation. System Types are included by enabling these, not by using types. |
visual_settings_id | The stored Visual Settings the Project has as default. |
types | The Types of the Project, in the order the Project shows them, each with the members below. |
date_types | The Types whose Sub-Objects a date can refer to. Empty means all but Classifications. |
location_types | The Types whose Objects a location can refer to. Empty means all Types and Reversals. |
source_types | The Types whose Objects data can cite as a source. |
use_projects | Other Projects whose stored features this Project uses. The form of a stored Project starts with the Project itself, so a Project that is added from a copy of that form keeps using the original Project's stored features. |
Each Type in types:
| Member | Description |
|---|---|
type_id | A Type of the nodegoat Domain's data Model. |
color | The colour of the Type in the Project, hexadecimal. |
type_information | Information shown with the Type, as HTML. |
type_edit | create to add and edit Objects, edit to edit them only, empty for neither. |
type_filter_id | A stored Filter that limits the Objects of the Type the Project shows. With type_filter_object_subs, it limits the Sub-Objects as well. |
type_condition_id | A stored Condition the Project applies to the Type. |
type_context_id,type_frame_id | The stored Context and Frame the Type starts with. |
configuration | What of the Type the Project shows and edits, keyed by Object Description, Sub-Object Details, and Sub-Object Description ID, each with view and edit. Left out means everything. Optional. |
configuration_exclude | true when configuration lists what is left out, instead of what is included. Only with a configuration. Optional. |
include_referenced_types | The Object Descriptions and Sub-Object Descriptions of other Types that reference this Type, shown and edited as part of it, keyed by the referencing Type ID. Optional. |
A Project that is added is linked to the user who stores it, as it is when added in nodegoat itself.
PUT
When submitting Projects with the PUT method, you can overwrite the Project specified in the path, overwrite the Projects specified in the submitted data, or create new Projects. An overwritten Project ends up exactly as submitted: any member of the form that is left out is reset.
To overwrite a Project specified in the path https://nodegoat.io/project/1, you submit a single Project dictionary:
PROJECTTo overwrite Projects specified in the submitted data, you access the path without an ID https://nodegoat.io/project/, create the key update, and provide a dictionary with the Project IDs as keys and Project dictionaries as values:
{
"update": {
"1": PROJECT,
"11": ...
}
}To add new Projects, you access the path without an ID https://nodegoat.io/project/, create the key add, and submit a list with Project dictionaries:
{
"add": [
PROJECT,
...
]
}To both add and update Projects in a single request, you access the path without an ID https://nodegoat.io/project/ and provide the key add with a list and the key update with a dictionary:
{
"add": [PROJECT, ...],
"update": {"1": PROJECT, "11": ...}
}PATCH
When submitting Projects with the PATCH method, you can update the Project specified in the path or update the Projects specified in the data. Any member that is not specified in the submitted data keeps its stored value, and so does any member of the form. A member of the form that is specified replaces its stored value as a whole: to change one Type in types, submit the full list.
To update a Project specified in the path https://nodegoat.io/project/1, you submit a single Project dictionary that only contains the data you want to update:
PROJECTTo update Projects specified in the submitted data, you access the path without an ID https://nodegoat.io/project/ and provide a dictionary with the Project IDs as keys and Project dictionaries as values:
{
"1": PROJECT,
"11": ...
}DELETE
To delete Projects, you either apply the method DELETE to the path to a specific Project, e.g. https://nodegoat.io/project/1 and submit no body, or you access the path without an ID and submit a dictionary with the Project IDs as keys:
{
"1": true,
"11": 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, feature, or Project IDs that have been added, updated, or deleted.