From 6e10fea119a4508052d63188bd791e19bc48501a Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <jstretch@digitalocean.com>
Date: Wed, 1 Feb 2017 14:04:45 -0500
Subject: [PATCH] Started API documentation

---
 docs/api/structure.md | 32 ++++++++++++++++++++++++++++++++
 mkdocs.yml            |  2 ++
 2 files changed, 34 insertions(+)
 create mode 100644 docs/api/structure.md

diff --git a/docs/api/structure.md b/docs/api/structure.md
new file mode 100644
index 000000000..437ba9bfd
--- /dev/null
+++ b/docs/api/structure.md
@@ -0,0 +1,32 @@
+# URL Hierarchy
+
+The API's URL structure is divided at the root level by application: circuits, DCIM, IPAM, secrets, and tenancy. Within each application, each model has its own path. For example:
+
+* /api/circuits/circuits/
+* /api/circuits/providers/
+* /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.
+
+* /api/dcim/devices/ - List devices or create a new device
+* /api/dcim/devices/123/ - Retrieve, update, or delete the device with ID 123
+
+Lists of objects can be filtered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
+
+* /api/dcim/interfaces/?device_id=123
+
+# Serializers
+
+The NetBox API employs three types of serializers to represent model data:
+
+* Base serializer
+* Nested serializer
+* Writable serializer
+
+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.
+
+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.
diff --git a/mkdocs.yml b/mkdocs.yml
index 9a96fe0f7..07f319468 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -19,6 +19,8 @@ pages:
         - 'Secrets': 'data-model/secrets.md'
         - 'Tenancy': 'data-model/tenancy.md'
         - 'Extras': 'data-model/extras.md'
+    - 'API':
+        - 'Structure': 'api/structure.md'
     - 'API Integration': 'api-integration.md'
 
 markdown_extensions: