Skip to content

Commit 09b7084

Browse files
authored
Add initial documentation (#44)
1 parent 0fede3e commit 09b7084

File tree

3 files changed

+322
-101
lines changed

3 files changed

+322
-101
lines changed

README.md

Lines changed: 14 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,26 @@
1-
# netbox-service-mappings
2-
Service Mappings plugin
1+
# NetBox Custom Objects
32

4-
1. Add `netbox_custom_objects` to `PLUGINS` in `configuration.py`.
3+
This [NetBox](https://netboxlabs.com/products/netbox/) plugin introduces the ability to create new object types in NetBox so that users can add models to suit their own needs. NetBox users have been able to extend the NetBox data model for some time using both Tags & Custom Fields and Plugins. Tags and Custom Fields are easy to use, but they have limitations when used at scale, and Plugins are very powerful but require Python/Django knowledge, and ongoing maintenance. Custom Objects provides users with a no-code "sweet spot" for data model extensibility, providing a lot of the power of NetBox plugins, but with the ease of use of Tags and Custom Fields.
4+
5+
You can find further documentation [here](docs/index.md).
6+
7+
## Requirements
8+
9+
* NetBox v4.2 or later
10+
11+
## Installation
12+
13+
1. Add `netboxlabs_netbox_custom_objects` to `PLUGINS` in `configuration.py`.
514

615
```python
716
PLUGINS = [
817
# ...
9-
'netbox_custom_objects',
18+
'netboxlabs_netbox_custom_objects',
1019
]
1120
```
1221

1322
2. Run NetBox migrations:
1423

1524
```
1625
$ ./manage.py migrate
17-
```
18-
19-
## API
20-
21-
The three relevant models making up the Service Mappings system can be manipulated through CRUD operations using the
22-
standard NetBox API, using endpoints located at: `/api/plugins/service-mappings/`
23-
24-
```json
25-
{
26-
"mapping-type-fields": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-type-fields/",
27-
"mapping-types": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-types/",
28-
"mappings": "http://127.0.0.1:8000/api/plugins/service-mappings/mappings/"
29-
}
30-
```
31-
32-
### Service Mapping Types
33-
34-
Create a Service Mapping Type with a POST call to `/api/plugins/service-mappings/mapping-types/` using a payload
35-
similar to the following:
36-
37-
```json
38-
{
39-
"name": "My Service Type",
40-
"slug": "my-service-type"
41-
}
42-
```
43-
44-
### Mapping Type Fields
45-
46-
Then define the schema of the Service Mapping Type by creating fields of various types, with POST requests to
47-
`/api/plugins/service-mappings/mapping-type-fields/`:
48-
49-
```json
50-
{
51-
"custom_object_type": 9,
52-
"name": "internal_id",
53-
"label": "Internal ID",
54-
"type": "integer",
55-
"options": {
56-
"min": 0,
57-
"max": 9999
58-
}
59-
}
60-
```
61-
62-
Available `type` values are: `char`, `integer`, `boolean`, `date`, `datetime`, `object`, and `multiobject`. Attributes for
63-
specific field types can be specified using the `options` object (details TBD).
64-
65-
If the type is `object` or `multiobject`, the content type of the field is designated using the `app_label` and `model` attributes
66-
as shown here:
67-
68-
```json
69-
{
70-
"custom_object_type": 9,
71-
"name": "single_device",
72-
"label": "Single Device",
73-
"type": "object",
74-
"app_label": "dcim",
75-
"model": "device"
76-
}
77-
```
78-
79-
```json
80-
{
81-
"custom_object_type": 9,
82-
"name": "device_list",
83-
"label": "Device List",
84-
"type": "multiobject",
85-
"app_label": "dcim",
86-
"model": "device"
87-
}
88-
```
89-
90-
!!! note
91-
An `object` or `multiobject` field can point to any Custom Object, as well as any other existing object internal to NetBox.
92-
Use an `app_label` of `netbox_custom_objects` and a `model` of `customobject`.
93-
94-
### Custom Objects
95-
96-
Once the schema of a Custom Object Type is defined through its list of fields, you can create Custom Objects,
97-
which are instances of Custom Object Types with specific values populated into the fields defined in the schema.
98-
Create a Custom Object with a POST to `/api/plugins/custom-objects/custom-objects/`:
99-
100-
```json
101-
{
102-
"custom_object_type": 9,
103-
"name": "My Object",
104-
"data": {
105-
"internal_id": 102,
106-
"device_list": [34, 1],
107-
"single_device": 16
108-
}
109-
}
110-
```
111-
112-
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
113-
URL for each model, i.e. `/api/plugins/custom-objects/custom-objects/15/`
26+
```

docs/api.md

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
## API
2+
3+
The NetBox Custom Objects plugin provides CRUD operations through the standard NetBox API, with endpoints located at: `/api/plugins/custom-objects/`
4+
5+
```json
6+
{
7+
"custom-object-types": "http://127.0.0.1:8000/api/plugins/custom-objects/custom-object-types/",
8+
"custom-object-type-fields": "http://127.0.0.1:8000/api/plugins/custom-objects/custom-object-type-fields/",
9+
"my-custom-type": "http://127.0.0.1:8000/api/plugins/custom-objects/my-custom-type/"
10+
}
11+
```
12+
13+
The plugin dynamically creates endpoints for each Custom Object Type you define. The endpoint names are based on the `name` of the Custom Object Type.
14+
15+
### Custom Object Types
16+
17+
Create a Custom Object Type with a POST call to `/api/plugins/custom-objects/custom-object-types/` using a payload
18+
similar to the following:
19+
20+
```json
21+
{
22+
"name": "Server",
23+
"description": "Server inventory objects",
24+
"verbose_name_plural": "Servers"
25+
}
26+
```
27+
28+
### Custom Object Type Fields
29+
30+
Define the schema of the Custom Object Type by creating fields of various types, with POST requests to
31+
`/api/plugins/custom-objects/custom-object-type-fields/`:
32+
33+
```json
34+
{
35+
"custom_object_type": 9,
36+
"name": "internal_id",
37+
"label": "Internal ID",
38+
"type": "integer",
39+
"required": true,
40+
"validation_minimum": 0,
41+
"validation_maximum": 9999
42+
}
43+
```
44+
45+
Available `type` values are:
46+
- `text` - Short text field
47+
- `longtext` - Long text field with textarea widget
48+
- `integer` - Integer field
49+
- `decimal` - Decimal field
50+
- `boolean` - Boolean field
51+
- `date` - Date field
52+
- `datetime` - DateTime field
53+
- `url` - URL field
54+
- `json` - JSON field
55+
- `select` - Single select from choice set
56+
- `multiselect` - Multiple select from choice set
57+
- `object` - Reference to a single object
58+
- `multiobject` - Reference to multiple objects
59+
60+
Field-specific attributes can be specified using the validation and configuration fields:
61+
62+
#### Text Fields (`text`, `longtext`)
63+
```json
64+
{
65+
"custom_object_type": 9,
66+
"name": "hostname",
67+
"label": "Hostname",
68+
"type": "text",
69+
"required": true,
70+
"validation_regex": "^[a-zA-Z0-9-]+$"
71+
}
72+
```
73+
74+
#### Numeric Fields (`integer`, `decimal`)
75+
```json
76+
{
77+
"custom_object_type": 9,
78+
"name": "cpu_cores",
79+
"label": "CPU Cores",
80+
"type": "integer",
81+
"validation_minimum": 1,
82+
"validation_maximum": 128
83+
}
84+
```
85+
86+
#### Choice Fields (`select`, `multiselect`)
87+
```json
88+
{
89+
"custom_object_type": 9,
90+
"name": "environment",
91+
"label": "Environment",
92+
"type": "select",
93+
"choice_set": 5
94+
}
95+
```
96+
97+
#### Object Reference Fields (`object`, `multiobject`)
98+
99+
If the type is `object` or `multiobject`, the content type of the field is designated using the `app_label` and `model` attributes:
100+
101+
```json
102+
{
103+
"custom_object_type": 9,
104+
"name": "primary_device",
105+
"label": "Primary Device",
106+
"type": "object",
107+
"app_label": "dcim",
108+
"model": "device"
109+
}
110+
```
111+
112+
```json
113+
{
114+
"custom_object_type": 9,
115+
"name": "device_list",
116+
"label": "Device List",
117+
"type": "multiobject",
118+
"app_label": "dcim",
119+
"model": "device"
120+
}
121+
```
122+
123+
> [!NOTE]
124+
> An `object` or `multiobject` field can point to any Custom Object, as well as any other existing object internal to NetBox.
125+
> Use an `app_label` of `custom-objects` and a `model` of the Custom Object name to reference other custom objects.
126+
127+
128+
### Custom Objects
129+
130+
Once the schema of a Custom Object Type is defined through its list of fields, you can create Custom Objects,
131+
which are instances of Custom Object Types with specific values populated into the fields defined in the schema.
132+
133+
Create a Custom Object with a POST to `/api/plugins/custom-objects/<custom-object-type>/` where `<custom-object-type>` is the name of your Custom Object Type:
134+
135+
```json
136+
{
137+
"internal_id": 102,
138+
"hostname": "server-001",
139+
"cpu_cores": 8,
140+
"environment": "production",
141+
"device_list": [34, 1],
142+
"primary_device": 16
143+
}
144+
```
145+
146+
The response will include the created object with its assigned ID and additional metadata:
147+
148+
```json
149+
{
150+
"id": 15,
151+
"url": "http://127.0.0.1:8000/api/plugins/custom-objects/server/15/",
152+
"custom_object_type": {
153+
"id": 9,
154+
"name": "Server",
155+
"description": "Server inventory objects"
156+
},
157+
"internal_id": 102,
158+
"hostname": "server-001",
159+
"cpu_cores": 8,
160+
"environment": "production",
161+
"device_list": [34, 1],
162+
"primary_device": 16,
163+
"tags": [],
164+
"created": "2024-01-15T10:30:00Z",
165+
"last_updated": "2024-01-15T10:30:00Z"
166+
}
167+
```
168+
169+
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
170+
URL for each model:
171+
- Custom Object Types: `/api/plugins/custom-objects/custom-object-types/15/`
172+
- Custom Object Type Fields: `/api/plugins/custom-objects/custom-object-type-fields/23/`
173+
- Custom Objects: `/api/plugins/custom-objects/<custom-object-type>/15/`

0 commit comments

Comments
 (0)