diff --git a/docs/v4/README.md b/docs/v4/README.md index d0326871..8b358528 100644 --- a/docs/v4/README.md +++ b/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 diff --git a/docs/v4/capsules/all.md b/docs/v4/capsules/all.md index 6d36d710..4e85c78f 100644 --- a/docs/v4/capsules/all.md +++ b/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" + }, + ... +] ``` diff --git a/docs/v4/capsules/create.md b/docs/v4/capsules/create.md index e69de29b..526a45d5 100644 --- a/docs/v4/capsules/create.md +++ b/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. diff --git a/docs/v4/capsules/delete.md b/docs/v4/capsules/delete.md index e69de29b..6ffd1227 100644 --- a/docs/v4/capsules/delete.md +++ b/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. diff --git a/docs/v4/capsules/one.md b/docs/v4/capsules/one.md index 3e725c9a..eaa8611a 100644 --- a/docs/v4/capsules/one.md +++ b/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` diff --git a/docs/v4/capsules/query.md b/docs/v4/capsules/query.md index e69de29b..f08f32a3 100644 --- a/docs/v4/capsules/query.md +++ b/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. diff --git a/docs/v4/capsules/schema.md b/docs/v4/capsules/schema.md new file mode 100644 index 00000000..ba82a21c --- /dev/null +++ b/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", + }], +} +``` diff --git a/docs/v4/capsules/update.md b/docs/v4/capsules/update.md index e69de29b..9f54e0f0 100644 --- a/docs/v4/capsules/update.md +++ b/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. diff --git a/docs/v4/queries.md b/docs/v4/queries.md new file mode 100644 index 00000000..f4f8f1ff --- /dev/null +++ b/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 + } +} +```