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 also include the store operations: / project / ID .openapi includes the store operations of the specified Project, / project / .openapi those of the Projects' 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 store multiple features in a single request, specify them with their IDs as keys in the submitted data. The method DELETE accepts multiple IDs:/ 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
Types that are shared from another nodegoat Domain and system Types cannot be deleted. When a request includes such a Type, the request is refused and none of its Types are 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 ID of the Type the feature applies to. Required when adding a feature. The Type of a stored feature cannot be changed. |
name | The name of the feature. |
description | A description of the feature's purpose, to inform users who select it from the Project's stored features. Optional. |
usage | The availability of the feature: personal for the user who stores it, project for all users of the Project, or admin for all Projects. personal is the default when not included. The usage admin requires administrator clearance, and is not available for Scopes. The usage of a stored feature cannot be changed. Optional. |
form | The configuration of the Filter, Scope, or Condition, formatted as returned when accessing / feature / filter, / feature / scope, or / feature / condition. These responses describe how a form is composed, and list the Project's stored forms as examples that can be copied and adjusted. |
| Condition | |
form_model_conditions | 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 applies to stored Conditions: a Condition that is passed to a query as a form applies to the queried Type only. Optional. |
Features that belong to another user, or that are maintained by nodegoat through 'auto-store', cannot be changed. A request that submits a different Type or usage for a stored feature is refused.
The submitted form is validated 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 without effect, the request is refused with a message that states the invalid reference or instruction.
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 will not be touched. For instance, this allows you to change a feature's name without resubmitting its form.
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 part of a submitted Project dictionary: 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 configuration of the Project, formatted as returned when accessing / project with administrator clearance. Its members are described 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) refer to features of the Project itself, or of a Project in use_projects. An ID that is not set is null.
| Member | Description |
|---|---|
full_scope_enable | Enable traversal of all Types in the nodegoat Domain, not only the Types of the Project. |
source_referencing_enable | Enable source referencing: data can reference Objects of the source_types as sources. |
discussion_enable | Enable a discussion for each Object. |
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 ID of the stored Visual Settings that are the default of the Project. |
types | The Types included in the Project, in the order they are presented. Each Type has the members described below. |
date_types | The Types whose Sub-Objects can be referenced by a date. When empty, all Types except Classifications are available. |
location_types | The Types whose Objects can be referenced by a location. When empty, all Types and Reversals are available. |
source_types | The Types whose Objects can be referenced as a source. |
use_projects | Other Projects whose stored features are available in this Project. The form of a stored Project lists the Project itself first, so a Project that is added from a copy of that form continues to use the stored features of the original Project. |
Each Type in types:
| Member | Description |
|---|---|
type_id | The ID of a Type in the nodegoat Domain's data Model. |
color | The colour of the Type in the Project, as a hexadecimal value. |
type_information | Information presented with the Type, formatted as HTML. |
type_edit | create allows adding and editing Objects, edit allows editing Objects only, empty allows neither. |
type_filter_id | The ID of a stored Filter that limits the Objects of the Type that are available in the Project. When type_filter_object_subs is true, the Filter also limits the Sub-Objects. |
type_condition_id | The ID of a stored Condition that is applied to the Type in the Project. |
type_context_id,type_frame_id | The IDs of the stored Context and Frame that are applied to the Type by default. |
configuration | The Object Descriptions, Sub-Object Details, and Sub-Object Descriptions of the Type that can be viewed and edited in the Project, with their IDs as keys and view and edit as values. When not included, the full Type is available. Optional. |
configuration_exclude | When true, configuration lists what is excluded instead of what is included. Applies only in combination with configuration. Optional. |
include_referenced_types | The Object Descriptions and Sub-Object Descriptions of other Types that reference this Type, to be viewed and edited as part of this Type, with the IDs of the referencing Types as keys. Optional. |
A Project that is added is linked to the user who stores it, the same as when a Project is added through the nodegoat interface.
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 is stored exactly as submitted: any member of the form that is not included is reset to its default.
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 will not be touched, including any member of the form. A member of the form that is specified replaces its stored value entirely: 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.