Skip to content

Commit 8b2d72e

Browse files
mrmrcolemanmrmrcoleman
committed
Updated api docs
1 parent fdce600 commit 8b2d72e

File tree

1 file changed

+112
-34
lines changed

1 file changed

+112
-34
lines changed

‎docs/api.md

Lines changed: 112 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,108 @@
11
## API
22

3-
The three relevant models making up the Service Mappings system can be manipulated through CRUD operations using the
4-
standard NetBox API, using endpoints located at: `/api/plugins/service-mappings/`
3+
The NetBox Custom Objects plugin provides CRUD operations through the standard NetBox API, with endpoints located at: `/api/plugins/custom-objects/`
54

65
```json
76
{
8-
"mapping-type-fields": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-type-fields/",
9-
"mapping-types": "http://127.0.0.1:8000/api/plugins/service-mappings/mapping-types/",
10-
"mappings": "http://127.0.0.1:8000/api/plugins/service-mappings/mappings/"
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/"
1110
}
1211
```
1312

14-
### Service Mapping Types
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.
1514

16-
Create a Service Mapping Type with a POST call to `/api/plugins/service-mappings/mapping-types/` using a payload
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
1718
similar to the following:
1819

1920
```json
2021
{
21-
"name": "My Service Type",
22-
"slug": "my-service-type"
22+
"name": "Server",
23+
"description": "Server inventory objects",
24+
"verbose_name_plural": "Servers"
2325
}
2426
```
2527

26-
### Mapping Type Fields
28+
### Custom Object Type Fields
2729

28-
Then define the schema of the Service Mapping Type by creating fields of various types, with POST requests to
29-
`/api/plugins/service-mappings/mapping-type-fields/`:
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/`:
3032

3133
```json
3234
{
3335
"custom_object_type": 9,
3436
"name": "internal_id",
3537
"label": "Internal ID",
3638
"type": "integer",
37-
"options": {
38-
"min": 0,
39-
"max": 9999
40-
}
39+
"required": true,
40+
"validation_minimum": 0,
41+
"validation_maximum": 9999
4142
}
4243
```
4344

44-
Available `type` values are: `char`, `integer`, `boolean`, `date`, `datetime`, `object`, and `multiobject`. Attributes for
45-
specific field types can be specified using the `options` object (details TBD).
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+
```
4673

47-
If the type is `object` or `multiobject`, the content type of the field is designated using the `app_label` and `model` attributes
48-
as shown here:
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+
```
4985

86+
#### Choice Fields (`select`, `multiselect`)
5087
```json
5188
{
5289
"custom_object_type": 9,
53-
"name": "single_device",
54-
"label": "Single Device",
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",
55106
"type": "object",
56107
"app_label": "dcim",
57108
"model": "device"
@@ -69,27 +120,54 @@ as shown here:
69120
}
70121
```
71122

72-
!!! note
73-
An `object` or `multiobject` field can point to any Custom Object, as well as any other existing object internal to NetBox.
74-
Use an `app_label` of `netbox_custom_objects` and a `model` of `customobject`.
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+
75127

76128
### Custom Objects
77129

78130
Once the schema of a Custom Object Type is defined through its list of fields, you can create Custom Objects,
79131
which are instances of Custom Object Types with specific values populated into the fields defined in the schema.
80-
Create a Custom Object with a POST to `/api/plugins/custom-objects/custom-objects/`:
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:
81134

82135
```json
83136
{
84-
"custom_object_type": 9,
85-
"name": "My Object",
86-
"data": {
87-
"internal_id": 102,
88-
"device_list": [34, 1],
89-
"single_device": 16
90-
}
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"
91166
}
92167
```
93168

94169
PATCH requests can be used to update all the above objects, as well as DELETE and GET operations, using the detail
95-
URL for each model, i.e. `/api/plugins/custom-objects/custom-objects/15/`
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)