Expanded API documentation

docs/api/authentication.md

@@ -0,0 +1,48 @@
+The NetBox API employs token-based authentication. For convenience, cookie authentication can also be used when navigating the browsable API.
+
+# Tokens
+
+A token is a unique identifier that identifies a user to the API. Each user in NetBox may have one or more tokens which he or she can use to authenticate to the API. To create a token, navigate to the API tokens page at `/user/api-tokens/`.
+
+Each token contains a 160-bit key represented as 40 hexadecimal characters. When creating a token, you'll typically leave the key field blank so that a random key will be automatically generated. However, NetBox allows you to specify a key in case you need to restore a previously deleted token to operation.
+
+By default, a token can be used for all operations available via the API. Deselecting the "write enabled" option will restrict API requests made with the token to read operations (e.g. GET) only.
+
+Additionally, a token can be set to expire at a specific time. This can be useful if an external client needs to be granted temporary access to NetBox.
+
+# Authenticating to the API
+
+By default, read operations will be available without authentication. In this case, a token may be included in the request, but is not necessary.
+
+```
+$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/
+{
+    "count": 10,
+    "next": null,
+    "previous": null,
+    "results": [...]
+}
+```
+
+However, if the `[LOGIN_REQUIRED](../configuration/optional-settings/#login_required)` configuration setting has been set to `True`, all requests must be authenticated.
+
+```
+$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/
+{
+    "detail": "Authentication credentials were not provided."
+}
+```
+
+To authenticate to the API, set the HTTP `Authorization` header to the string `Token ` (note the trailing space) followed by the token key.
+
+```
+$ curl -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/
+{
+    "count": 10,
+    "next": null,
+    "previous": null,
+    "results": [...]
+}
+```
+
+Additionally, the browsable interface to the API (which can be seen by navigating to the API root `/api/` in a web browser) will attempt to authenticate requests using the same cookie that the normal NetBox front end uses. Thus, if you have logged into NetBox, you will be logged into the browsable API as well.

docs/api/examples.md

@@ -0,0 +1,138 @@
+# API Examples
+
+Supported HTTP methods:
+
+* `GET`: Retrieve an object or list of objects
+* `POST`: Create a new object
+* `PUT`: Update an existing object
+* `DELETE`: Delete an existing object
+
+To authenticate a request, attach your token in an `Authorization` header:
+
+```
+curl -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0"
+```
+
+### Retrieving a list of sites
+
+Send a `GET` request to the object list endpoint. The response contains a paginated list of JSON objects.
+
+```
+$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/
+{
+    "count": 14,
+    "next": null,
+    "previous": null,
+    "results": [
+        {
+            "id": 6,
+            "name": "Corporate HQ",
+            "slug": "corporate-hq",
+            "region": null,
+            "tenant": null,
+            "facility": "",
+            "asn": null,
+            "physical_address": "742 Evergreen Terrace, Springfield, USA",
+            "shipping_address": "",
+            "contact_name": "",
+            "contact_phone": "",
+            "contact_email": "",
+            "comments": "",
+            "custom_fields": {},
+            "count_prefixes": 108,
+            "count_vlans": 46,
+            "count_racks": 8,
+            "count_devices": 254,
+            "count_circuits": 6
+        },
+        ...
+    ]
+}
+```
+
+### Retrieving a single site by ID
+
+Send a `GET` request to the object detail endpoint. The response contains a single JSON object.
+
+```
+$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/6/
+{
+    "id": 6,
+    "name": "Corporate HQ",
+    "slug": "corporate-hq",
+    "region": null,
+    "tenant": null,
+    "facility": "",
+    "asn": null,
+    "physical_address": "742 Evergreen Terrace, Springfield, USA",
+    "shipping_address": "",
+    "contact_name": "",
+    "contact_phone": "",
+    "contact_email": "",
+    "comments": "",
+    "custom_fields": {},
+    "count_prefixes": 108,
+    "count_vlans": 46,
+    "count_racks": 8,
+    "count_devices": 254,
+    "count_circuits": 6
+}
+```
+
+### Creating a new site
+
+Send a `POST` request to the site list endpoint with token authentication and JSON-formatted data. Only mandatory fields are required.
+
+```
+$ curl -X POST -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/ --data '{"name": "My New Site", "slug": "my-new-site"}'
+{
+    "id": 16,
+    "name": "My New Site",
+    "slug": "my-new-site",
+    "region": null,
+    "tenant": null,
+    "facility": "",
+    "asn": null,
+    "physical_address": "",
+    "shipping_address": "",
+    "contact_name": "",
+    "contact_phone": "",
+    "contact_email": "",
+    "comments": ""
+}
+```
+
+### Modify an existing site
+
+Make an authenticated `PUT` request to the site detail endpoint. As with a create (POST) request, all mandatory fields must be included.
+
+```
+$ curl -X PUT -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/16/ --data '{"name": "Renamed Site", "slug": "renamed-site"}'
+```
+
+### Delete an existing site
+
+Send an authenticated `DELETE` request to the site detail endpoint.
+
+```
+$ curl -v X DELETE -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/16/
+* Connected to localhost (127.0.0.1) port 8000 (#0)
+> DELETE /api/dcim/sites/16/ HTTP/1.1
+> User-Agent: curl/7.35.0
+> Host: localhost:8000
+> Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0
+> Content-Type: application/json
+> Accept: application/json; indent=4
+>
+* HTTP 1.0, assume close after body
+< HTTP/1.0 204 No Content
+< Date: Mon, 20 Mar 2017 16:13:08 GMT
+< Server: WSGIServer/0.1 Python/2.7.6
+< Vary: Accept, Cookie
+< X-Frame-Options: SAMEORIGIN
+< Allow: GET, PUT, PATCH, DELETE, OPTIONS
+<
+* Closing connection 0
+```
+
+The response to a successfull `DELETE` request will have code 204 (No Content); the body of the response will be empty.

docs/api/structure.md

@@ -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
 
-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/circuits/
+
+Likewise, the site, rack, and device objects are located under the "DCIM" application:
+
 * /api/dcim/sites/
 * /api/dcim/racks/
 * /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/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
 ```
 
-# Serializers
+# Serialization
 
 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.
 
+```
+{
+    "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.
 
 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": ""
+}
+```

mkdocs.yml

@@ -20,7 +20,9 @@ pages:
         - 'Tenancy': 'data-model/tenancy.md'
         - 'Extras': 'data-model/extras.md'
     - 'API':
-        - 'Structure': 'api/structure.md'
+        - 'Overview': 'api/overview.md'
+        - 'Authentication': 'api/authentication.md'
+        - 'Examples': 'api/examples.md'
 
 markdown_extensions:
     - admonition: