|
@@ -1,14 +1,21 @@
|
|
|
|
+NetBox v2.0 and later includes a full-featured REST API that allows its data model to be read and manipulated externally.
|
|
|
|
+
|
|
# URL Hierarchy
|
|
# URL Hierarchy
|
|
|
|
|
|
-NetBox's entire REST API is housed under the API root, `/api/`. The API's URL structure is divided at the root level by application: circuits, DCIM, extras, IPAM, secrets, and tenancy. Within each application, each model has its own path. For example:
|
|
+NetBox's entire REST API is housed under the API root, `/api/`. The API's URL structure is divided at the root level by application: circuits, DCIM, extras, IPAM, secrets, and tenancy. Within each application, each model has its own path. For example, the provider and circuit objects are located under the "circuits" application:
|
|
|
|
|
|
* /api/circuits/providers/
|
|
* /api/circuits/providers/
|
|
* /api/circuits/circuits/
|
|
* /api/circuits/circuits/
|
|
|
|
+
|
|
|
|
+Likewise, the site, rack, and device objects are located under the "DCIM" application:
|
|
|
|
+
|
|
* /api/dcim/sites/
|
|
* /api/dcim/sites/
|
|
* /api/dcim/racks/
|
|
* /api/dcim/racks/
|
|
* /api/dcim/devices/
|
|
* /api/dcim/devices/
|
|
|
|
|
|
-Each model generally has two URLs associated with it: a list URL and a detail URL. The list URL is used to request a list of multiple objects or to create a new object. The detail URL is used to retrieve, update, or delete an existing object.
|
|
+The full hierarchy of available endpoints can be viewed by navigating to the API root (e.g. /api/) in a web browser.
|
|
|
|
+
|
|
|
|
+Each model generally has two URLs associated with it: a list URL and a detail URL. The list URL is used to request a list of multiple objects or to create a new object. The detail URL is used to retrieve, update, or delete an existing object. All objects are referenced by their numeric primary key (ID).
|
|
|
|
|
|
* /api/dcim/devices/ - List devices or create a new device
|
|
* /api/dcim/devices/ - List devices or create a new device
|
|
* /api/dcim/devices/123/ - Retrieve, update, or delete the device with ID 123
|
|
* /api/dcim/devices/123/ - Retrieve, update, or delete the device with ID 123
|
|
@@ -19,7 +26,7 @@ Lists of objects can be filtered using a set of query parameters. For example, t
|
|
GET /api/dcim/interfaces/?device_id=123
|
|
GET /api/dcim/interfaces/?device_id=123
|
|
```
|
|
```
|
|
|
|
|
|
-# Serializers
|
|
+# Serialization
|
|
|
|
|
|
The NetBox API employs three types of serializers to represent model data:
|
|
The NetBox API employs three types of serializers to represent model data:
|
|
|
|
|
|
@@ -29,6 +36,54 @@ The NetBox API employs three types of serializers to represent model data:
|
|
|
|
|
|
The base serializer is used to represent the default view of a model. This includes all database table fields which comprise the model, and may include additional metadata. A base serializer includes relationships to parent objects, but **does not** include child objects. For example, the `VLANSerializer` includes a nested representation its parent VLANGroup (if any), but does not include any assigned Prefixes.
|
|
The base serializer is used to represent the default view of a model. This includes all database table fields which comprise the model, and may include additional metadata. A base serializer includes relationships to parent objects, but **does not** include child objects. For example, the `VLANSerializer` includes a nested representation its parent VLANGroup (if any), but does not include any assigned Prefixes.
|
|
|
|
|
|
|
|
+```
|
|
|
|
+{
|
|
|
|
+ "id": 1048,
|
|
|
|
+ "site": {
|
|
|
|
+ "id": 7,
|
|
|
|
+ "url": "http://localhost:8000/api/dcim/sites/7/",
|
|
|
|
+ "name": "Corporate HQ",
|
|
|
|
+ "slug": "corporate-hq"
|
|
|
|
+ },
|
|
|
|
+ "group": {
|
|
|
|
+ "id": 4,
|
|
|
|
+ "url": "http://localhost:8000/api/ipam/vlan-groups/4/",
|
|
|
|
+ "name": "Production",
|
|
|
|
+ "slug": "production"
|
|
|
|
+ },
|
|
|
|
+ "vid": 101,
|
|
|
|
+ "name": "Users-Floor1",
|
|
|
|
+ "tenant": null,
|
|
|
|
+ "status": [
|
|
|
|
+ 1,
|
|
|
|
+ "Active"
|
|
|
|
+ ],
|
|
|
|
+ "role": {
|
|
|
|
+ "id": 9,
|
|
|
|
+ "url": "http://localhost:8000/api/ipam/roles/9/",
|
|
|
|
+ "name": "User Access",
|
|
|
|
+ "slug": "user-access"
|
|
|
|
+ },
|
|
|
|
+ "description": "",
|
|
|
|
+ "display_name": "101 (Users-Floor1)",
|
|
|
|
+ "custom_fields": {}
|
|
|
|
+}
|
|
|
|
+```
|
|
|
|
+
|
|
Related objects (e.g. `ForeignKey` fields) are represented using a nested serializer. A nested serializer provides a minimal representation of an object, including only its URL and enough information to construct its name.
|
|
Related objects (e.g. `ForeignKey` fields) are represented using a nested serializer. A nested serializer provides a minimal representation of an object, including only its URL and enough information to construct its name.
|
|
|
|
|
|
When a base serializer includes one or more nested serializers, the hierarchical structure precludes it from being used for write operations. Thus, a flat representation of an object may be provided using a writable serializer. This serializer includes only raw database values and is not typically used for retrieval, except as part of the response to the creation or updating of an object.
|
|
When a base serializer includes one or more nested serializers, the hierarchical structure precludes it from being used for write operations. Thus, a flat representation of an object may be provided using a writable serializer. This serializer includes only raw database values and is not typically used for retrieval, except as part of the response to the creation or updating of an object.
|
|
|
|
+
|
|
|
|
+```
|
|
|
|
+{
|
|
|
|
+ "id": 1201,
|
|
|
|
+ "site": 7,
|
|
|
|
+ "group": 4,
|
|
|
|
+ "vid": 102,
|
|
|
|
+ "name": "Users-Floor2",
|
|
|
|
+ "tenant": null,
|
|
|
|
+ "status": 1,
|
|
|
|
+ "role": 9,
|
|
|
|
+ "description": ""
|
|
|
|
+}
|
|
|
|
+```
|