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

@@ -1,4 +1,4 @@
-Retrieves a list of objects
+## List objects
 
 ### Querying
 

docs/api/op_retrieve.md

@@ -1,8 +1,8 @@
-Retrieves single object
+## Retrieve a single object
 
 ### Depth
 
-Nested sets will not be loaded (any field ending with the _set suffix) unless the '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:

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

docs/api_create.md

@@ -1 +0,0 @@
-Creates new object

docs/api_delete.md

@@ -1 +0,0 @@
-Marks object as deleted

docs/api_update.md

@@ -1 +0,0 @@
-Updates existing object