add v4 capsules docs

docs/v4/README.md

@@ -28,7 +28,7 @@ By default the body is:
 
 `query` accepts any valid MongoDB find() query, documented [here](https://docs.mongodb.com/manual/tutorial/query-documents/)
 
-See [examples](examples.md) for some common queries
+See [query](queries.md) guide for more details and some common queries.
 
 **Note:** The [$where](https://docs.mongodb.com/manual/reference/operator/query/where/) operator is not supported in `query`. [$expr](https://docs.mongodb.com/manual/reference/operator/query/expr/) should be used instead for complex query expressions
 
@@ -75,7 +75,7 @@ Cache can be cleared with the following endpoint:
 
 ## Routes
 
-### Capsules
+### Capsules - [Schema](capsules/schema.md)
 
 Detailed info for serialized dragon capsules
 
@@ -93,9 +93,9 @@ Detailed info for serialized first stage cores
 * [Get all cores](cores/get.md) : `GET /cores`
 * [Get one core](cores/one.md) : `GET /v4/cores/:id`
 * [Query cores](cores/query.md) : `POST /cores/query`
-* 🔒 [Create a core](cores/create.md) : `POST /cores` - 🔒
-* 🔒 [Update a core](cores/update.md) : `PATCH /cores/:id` - 🔒
-* 🔒 [Delete a core](cores/delete.md) : `DELETE /cores/:id` - 🔒
+* 🔒 [Create a core](cores/create.md) : `POST /cores`
+* 🔒 [Update a core](cores/update.md) : `PATCH /cores/:id`
+* 🔒 [Delete a core](cores/delete.md) : `DELETE /cores/:id`
 
 ### Crew
 

docs/v4/capsules/all.md

@@ -1,27 +1,29 @@
 # Get all capsules
 
-**URL** : `/capsules`
-
 **Method** : `GET`
 
-**Auth required** : NO
-
-## Success Responses
-
-**Condition** : User can not see any capsules.
-
-**Code** : `200 OK`
-
-**Content** : `[]`
+**URL** : `/capsules`
 
-### OR
+**Auth required** : `False`
 
-**Condition** : User can see one or more capsules.
+## Success Responses
 
 **Code** : `200 OK`
 
-**Content** : All capsules are shown
-
 ```json
-[]
+[
+    {
+        "reuse_count": 1,
+        "water_landings": 1,
+        "land_landings": 0,
+        "last_update": "Reentered after three weeks in orbit",
+        "launches": [
+            "5eb87cdeffd86e000604b330"
+        ],
+        "serial": "C101",
+        "status": "retired",
+        "id": "5e9e2c5bf35918ed873b2664"
+    },
+    ...
+]
 ```

docs/v4/capsules/create.md

@@ -0,0 +1,36 @@
+# Create a capsule
+
+**Method** : `POST`
+
+**URL** : `/capsules`
+
+**Auth required** : `True`
+
+**Body** :
+
+```json
+{
+    "reuse_count": 1,
+    "water_landings": 1,
+    "land_landings": 0,
+    "last_update": "Reentered after three weeks in orbit",
+    "launches": [
+        "5eb87cdeffd86e000604b330"
+    ],
+    "serial": "C101",
+    "status": "retired",
+    "id": "5e9e2c5bf35918ed873b2664"
+}
+```
+
+## Success Response
+
+**Code** : `201 Created`
+
+**Content example** : `Created`
+
+## Error Responses
+
+**Code** : `400 Bad Request`
+
+**Content** : Mongoose error is shown, with suggestions to fix the query.

docs/v4/capsules/delete.md

@@ -0,0 +1,21 @@
+# Delete a capsule
+
+**Method** : `DELETE`
+
+**URL** : `/capsules/:id`
+
+**URL Parameters** : `id=[string]` where `id` is the ID of the capsule
+
+**Auth required** : `True`
+
+## Success Response
+
+**Code** : `200 OK`
+
+**Content example** : `OK`
+
+## Error Responses
+
+**Code** : `400 Bad Request`
+
+**Content** : Mongoose error is shown, with suggestions to fix the query.

docs/v4/capsules/one.md

@@ -1,31 +1,36 @@
 # Get one capsule
 
+**Method** : `GET`
+
 **URL** : `/capsules/:id`
 
 **URL Parameters** : `id=[string]` where `id` is the ID of the capsule
 
-**Method** : `GET`
-
-**Auth required** : NO
+**Auth required** : `False`
 
 ## Success Response
 
-**Condition** : If capsule exists
-
 **Code** : `200 OK`
 
-**Content example**
+**Content example** :
 
 ```json
 {
-
+    "reuse_count": 1,
+    "water_landings": 1,
+    "land_landings": 0,
+    "last_update": "Reentered after three weeks in orbit",
+    "launches": [
+        "5eb87cdeffd86e000604b330"
+    ],
+    "serial": "C101",
+    "status": "retired",
+    "id": "5e9e2c5bf35918ed873b2664"
 }
 ```
 
 ## Error Responses
 
-**Condition** : If Capsule does not exist with `id`.
-
 **Code** : `404 NOT FOUND`
 
 **Content** : `Not Found`

docs/v4/capsules/query.md

@@ -0,0 +1,60 @@
+# Query capsules
+
+**Method** : `POST`
+
+**URL** : `/capsules/query`
+
+**Auth required** : `False`
+
+**Body** :
+
+See [query](../queries) guide for more details on building queries and paginating results.
+
+```json
+{
+  "query": {},
+  "options": {}
+}
+```
+
+## Success Response
+
+**Code** : `200 OK`
+
+**Content example** :
+
+```json
+{
+    "docs": [
+        {
+            "reuse_count": 1,
+            "water_landings": 1,
+            "land_landings": 0,
+            "last_update": "Reentered after three weeks in orbit",
+            "launches": [
+                "5eb87cdeffd86e000604b330"
+            ],
+            "serial": "C101",
+            "status": "retired",
+            "id": "5e9e2c5bf35918ed873b2664"
+        },
+        ...
+    ],
+    "totalDocs": 19,
+    "offset": 0,
+    "limit": 10,
+    "totalPages": 2,
+    "page": 1,
+    "pagingCounter": 1,
+    "hasPrevPage": false,
+    "hasNextPage": true,
+    "prevPage": null,
+    "nextPage": 2
+}
+```
+
+## Error Responses
+
+**Code** : `400 Bad Request`
+
+**Content** : Mongoose error is shown, with suggestions to fix the query.

docs/v4/capsules/schema.md

@@ -0,0 +1,38 @@
+# Capsule Schema
+
+```json
+{
+  "serial": {
+    "type": "String",
+    "required": true,
+    "unique": true,
+  },
+  "status": {
+    "type": "String",
+    "enum": ["unknown", "active", "retired", "destroyed"],
+    "required": true,
+  },
+  "dragon": {
+    "type": "UUID",
+  },
+  "reuse_count": {
+    "type": "Number",
+    "default": 0,
+  },
+  "water_landings": {
+    "type": "Number",
+    "default": 0,
+  },
+  "land_landings": {
+    "type": "Number",
+    "default": 0,
+  },
+  "last_update": {
+    "type": "String",
+    "default": null,
+  },
+  "launches": [{
+    "type": "UUID",
+  }],
+}
+```

docs/v4/capsules/update.md

@@ -0,0 +1,29 @@
+# Update a capsule
+
+**Method** : `PUT`
+
+**URL** : `/capsules/:id`
+
+**URL Parameters** : `id=[string]` where `id` is the ID of the capsule
+
+**Auth required** : `True`
+
+**Body** :
+
+```json
+{
+  "status": "retired",
+}
+```
+
+## Success Response
+
+**Code** : `200 OK`
+
+**Content example** : `OK`
+
+## Error Responses
+
+**Code** : `400 Bad Request`
+
+**Content** : Mongoose error is shown, with suggestions to fix the query.

docs/v4/queries.md

@@ -0,0 +1,76 @@
+# Query examples
+
+### Query between 2 dates
+
+Dates need to be ISO 8601 friendly for these operators to work properly
+
+```json
+{
+	"query": {
+		"date_utc": {
+			"$gte": "2017-06-22T00:00:00.000Z",
+			"$lte": "2017-06-25T00:00:00.000Z"
+		}
+	}
+}
+```
+
+### Full text search
+
+Generally this will search all text indexes in a collection. All string fields get indexed
+
+See the mongo [reference](https://docs.mongodb.com/manual/reference/operator/query/text/) for more details on additional operators.
+
+```json
+{
+	"query": {
+		"$text": {
+			"$search": "crs"
+		}
+	}
+}
+```
+
+Note: Full text search using `$text` will search all text index fields in a document, with no way to restrict to a specific field. The closest way to fuzzy match on an individual field is through the [$regex](https://docs.mongodb.com/manual/reference/operator/query/regex/) operator. 
+
+```json
+{
+	"query": {
+		"serial": {
+			"$regex": "/^crs/i"
+		}
+	}
+}
+```
+
+### Complex Query
+
+```json
+{
+	"query": {
+		"date_utc": {
+			"$gte": "2017-06-22T00:00:00.000Z",
+			"$lte": "2017-06-25T00:00:00.000Z"
+		},
+		"$or": [
+			{
+				"flight_number": {
+					"$gt": 30
+				}
+			},
+			{
+				"tbd": true
+			}
+		],
+		"date_precision": {
+			"$in": ["month", "day"]
+		}
+	},
+	"options": {
+		"sort": {
+			"flight_number": "asc"
+		},
+		"limit": 50
+	}
+}
+```