new api docs (#626)

docs/api/how_to_contribute.md

@@ -0,0 +1,17 @@
+# Contributing to the API documentation
+
+The openapi schema that is used to render the API documentation is generated automatically. However it
+is possible for the community to contribute to and augment the documentation by editing the files
+located in this (`/docs/api/`) directory.
+
+The contents of these files are joined into the various openapi description fields when the schema file
+is regenerated.
+
+Note that changes to these files won't show up in the documentation until the openapi schema file is 
+regenerated and redeployed.
+
+## Regenerating the schema
+
+```
+python manage.py generateschema > peeringdb_server/static/api-schema.yaml
+```

docs/api/obj_fac.md

@@ -0,0 +1,12 @@
+## Facility (Datacenter) 
+
+Identified by the `fac` tag.
+
+### Parent relationship:
+
+- `org` organization
+
+### Relationship(s):
+
+- `ixfac` exchange / facility presence
+- `netfac` network / facility presence

docs/api/obj_ix.md

@@ -0,0 +1,12 @@
+## Internet Exchange
+
+Identified by the `ix` tag.
+
+### Parent relationship:
+
+- `org` organization
+
+### Relationship(s):
+
+- `ixlan` internet exchange network information
+- `ixfac` exchange / facility presence

docs/api/obj_ixfac.md

@@ -0,0 +1,11 @@
+## Internet Exchange / Facility presence 
+
+Identified by the `ixfac` tag.
+
+### Parent relationship:
+
+- `ix` internet exchange
+
+### Relationship(s):
+
+- `fac` facility

docs/api/obj_ixlan.md

@@ -0,0 +1,12 @@
+## Internet Exchange Network Information
+
+Identified by the `ixlan` tag.
+
+### Parent relationship:
+
+- `ix` internet exchange
+
+### Relationship(s):
+
+- `ixpfx` prefixes
+- `netixlan` network to exchange connections (through ixlan)

docs/api/obj_ixpfx.md

@@ -0,0 +1,11 @@
+## Internet Exchange Prefix 
+
+Identified by the `ixpfx` tag.
+
+### Parent relationship:
+
+- `ix` internet exchange
+
+### Relationship(s):
+
+- None

docs/api/obj_net.md

@@ -0,0 +1,13 @@
+## Network
+
+Identified by the `net` tag.
+
+### Parent relationship:
+
+- `org` organization
+
+### Relationship(s):
+
+- `netixlan` network to exchange connections (through `ixlan`)
+- `netfac` network / facility presence
+- `poc` points of contact

docs/api/obj_netfac.md

@@ -0,0 +1,11 @@
+## Network / Facility presence 
+
+Identified by the `netfac` tag.
+
+### Parent relationship:
+
+- `net` network
+
+### Relationship(s):
+
+- `fac` facility

docs/api/obj_netixlan.md

@@ -0,0 +1,11 @@
+## Network to Internet Exchange connection 
+
+Identified by the `netixlan` tag.
+
+### Parent relationship:
+
+- `net` network
+
+### Relationship(s):
+
+- `ixlan` internet exchange network information

docs/api/obj_org.md

@@ -0,0 +1,15 @@
+## Organization
+
+Identified by the `org` tag.
+
+The organization is at the top of the peeringdb object hierarchy.
+
+### Parent relationship:
+
+- None
+
+### Children relationship(s):
+
+- `net` networks
+- `fac` facilities
+- `ix` exchanges

docs/api/obj_poc.md

@@ -0,0 +1,11 @@
+## Network Point of Contact 
+
+Identified by the `poc` tag.
+
+### Parent relationship:
+
+- `net` network
+
+### Relationship(s):
+
+- None 

docs/api/op_create.md

@@ -0,0 +1,23 @@
+## Creating objects
+
+### Status `pending`
+
+Some object types will be flagged as `pending` until they have been reviewed and approved by peeringdb staff.
+
+Currently this is the case for:
+
+
+- `org` organizations (only administrative staff users are currently allowed to create organizations)
+- `fac` facilities
+- `net` networks
+- `ix` exchanges
+- `ixpfx` prefixes (if part of a new exchange)
+- `ixlan` exchange networks (if part of a new exchange)
+
+### Permissions
+
+To be able to create an object, the requesting user requires `create` permissions to one of the
+object's parents in the relationship hierarchy.
+
+For example to create a `net` type object, the user needs to be permissioned to create in the organzation
+that is to be the network's holder entity.

docs/api/op_delete.md

@@ -0,0 +1 @@
+## Deleting objects

docs/api/op_list.md

@@ -0,0 +1,120 @@
+## List objects
+
+### Querying
+
+You may query the resultset by passing field names as url parameters
+
+### Numeric Queries
+
+On numeric fields you can suffix the field names with the following filters:
+
+- \_\_lt : less-than
+- \_\_lte : less-than-equal
+- \_\_gt : greater-than
+- \_\_gte : greater-than-equal
+- \_\_in : value inside set of values (comma separated)
+
+**examples**
+
+    ?<field_name>__lt=10
+    ?<field_name>__in=1,10
+
+### String Queries
+
+On string fields you can suffix the field names with the following filters:
+
+- \_\_contains : field value contains specified value
+- \_\_startswith : field value starts with specified value
+- \_\_in : value contained inside set of values (comma separated)
+
+**examples**
+
+    ?<field_name>__contains=something
+    ?<field_name>__in=this,that
+
+All string filtering operations are case-insensitive
+
+### Since
+
+
+You can use the since argument with a unix timestamp (seconds) to retrieve all
+objects updated since then. Note that this result will contain objects that were
+deleted in that timeframe as well - you can spot them by checking for status "deleted"
+
+**example**
+
+    ?since=1443414678
+
+### Nested data
+
+Any field ending in the suffix **_set** is a list of objects in a relationship with the parent
+object, you can expand those lists with the 'depth' parameter as explained below.
+
+The naming schema of the field will always tell you which type of object the set is holding
+and will correspond with the object's endpoint on the API
+
+    <object_type>_set
+
+So a set called 'net_set' will hold Network objects (api endpoint /net)
+
+### Depth
+
+Nested sets will not be loaded (any field ending with the _set suffix) unless the 'depth'
+parameter is passed in the request URL.
+
+Depth can be one of three values:
+
+  - 1 : expand sets into ids (slow)
+  - 2 : expand sets into objects (slower)
+  - 0 : dont expand sets at all (default behaviour)
+
+**example**
+
+    ?depth=1
+
+### Cached Responses
+
+Any request that does not require lookups will be served a cached result. Cache is updated approximately every 15 minutes.
+
+You can spot cached responses by checking for the "generated" property inside the "meta" object.
+
+    "meta" : {
+        // the cached data was last regenerated at this time (epoch)
+        "generated" : 1456121358.6301942
+    }
+
+**examples**
+
+will serve a cached result:
+
+    ?depth=2
+
+will serve a live result:
+
+    ?id__in=1,2
+
+### Resultset limit
+
+Any request that does lookup queries and has it's **depth** parameter specified will have a result limit of 250 entries, any entries past this limit will be truncated, at which point you either should be more specific with your query or use the skip and limit parameters to page through the result set
+
+**examples**
+
+will serve a live result and a maximum of 250 rows at a time:
+
+    ?updated__gt=2011-01-01&depth=1
+
+will serve a live result and will not be truncated:
+
+    ?updated__gt=2011-01-01
+
+will serve a cached result and will not be truncated:
+
+    ?depth=1
+
+### Pagination
+
+Use the skip and limit parameters to page through results
+
+    ?updated__gt=2011-01-01&depth=1&limit=250 - first page
+    ?updated__gt=2011-01-01&depth=1&limit=250&skip=250 - second page
+    ?updated__gt=2011-01-01&depth=1&limit=250&skip=500 - third page

docs/api/op_retrieve.md

@@ -0,0 +1,18 @@
+## Retrieve a single object
+
+### Depth
+
+Nested sets will not be expanded (any field ending with the _set suffix) unless the 'depth'
+parameter is passed in the request URL.
+
+Depth can be one of three values:
+
+  - 1 : expand sets into ids (slow)
+  - 2 : expand sets into objects (slower)
+  - 0 : dont expand sets at all (default behaviour)
+
+**example**
+
+    ?depth=1
+
+

docs/api/op_update.md

@@ -0,0 +1,5 @@
+## Update existing objects
+
+### Permissions
+
+In order to update an object the requesting user requires `update` permissions to the object itself or one of the parent relationships in the object hierarchy