refactor docs for new versioned routes

Author: jakewmeyer

README.md

@@ -20,7 +20,7 @@ Open Source REST API for launch, rocket, core, capsule, starlink, launchpad, and
 </h4>
 
 <h3 align="center">
-<a href="docs/v4/README.md">Docs</a> - <a href="docs/clients.md">API Clients</a> - <a href="docs/apps.md">Apps</a> - <a href="https://status.spacexdata.com">Status</a> - <a href="https://backups.spacexdata.com">Database Dumps</a>
+<a href="docs/README.md">Docs</a> - <a href="docs/clients.md">API Clients</a> - <a href="docs/apps.md">Apps</a> - <a href="https://status.spacexdata.com">Status</a> - <a href="https://backups.spacexdata.com">Database Dumps</a>
 <br/>
 </h3>
 

docs/README.md

@@ -0,0 +1,95 @@
+# r/SpaceX API Docs
+
+[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/ed4ed700dcc55b2c1f1c)
+
+## Disclaimer
+
+*We are not affiliated, associated, authorized, endorsed by, or in any way officially connected with Space Exploration Technologies Corp (SpaceX), or any of its subsidiaries or its affiliates. The names SpaceX as well as related names, marks, emblems and images are registered trademarks of their respective owners.*
+
+## Base URL
+
+`https://api.spacexdata.com`
+
+## Versioning
+
+Each route is individually versioned, see route list below for all avaliable versions. The API can also be pinned to the lastest version with `https://api.spacexdata.com/latest`, but only do this if you're cool with potential breaking changes.
+
+## Authentication
+
+Authentication via api key is required for all destructive routes. This includes all `create`, `update`, and `delete` routes.
+
+Authenticate by passing the header `spacex-key` with your api key. Protected routes return `401` without a valid key.
+
+## Pagination + Custom Queries
+
+All `/query` routes support pagination, custom queries, and other output controls.
+
+See the [pagination + query](queries.md) guide for more details and examples.
+
+## Launch date FAQ's
+
+* **Why does the date appear wrong?** - This is usually due to the way we store and display partial dates in the api. For example, a launch scheduled for `2020 July` would be represented as `2020-07-01T00:00:00.000Z`. In this case, the field `date_precision` would be set as `month`, meaning the date is only valid to the `month` level, or `2020-07`
+
+## Launch date field explanations
+
+* `date_utc` -  UTC launch date/time in ISO 8601 format
+
+* `date_unix` - UTC launch date/time as a UNIX timestamp in seconds
+
+* `date_local` -  Local launch time with time zone offset in ISO 8601 format
+
+* `date_precision` - Gives the date precision for partial dates. Valid values are `quarter`, `half`, `year`, `month`, `day`, `hour`.
+
+* `tbd` - Set as true if date is `To be determined`
+
+* `net` - Set as true if the date is `No earlier than`
+
+## Caching
+
+The api makes use of response caching via Redis for all `GET` requests, and `POST` requests on `/query` endpoints.
+
+Standard cache times are as follows:
+
+**launches** - 20 seconds
+
+**capsules**, **cores**, **launchpads**, **landpads**, **crew**, **ships**, **payloads** - 5 minutes
+
+**dragons**, **rockets** - 24 hours
+
+Cache can be cleared with the following endpoint:
+
+* 🔒 [Clear cache](cache/clear.md) : `DELETE /admin/cache`
+
+## Routes
+
+### [Capsules](capsules)
+
+### [Company Info](company)
+
+### [Cores](cores) - Detailed info for serialized first stage cores
+
+### [Crew](crew) - Detailed info on dragon crew members
+
+### [Dragons](dragons) - Detailed info about dragon capsule versions
+
+### [Landpads](landpads) - Detailed info about landing pads and ships
+
+### [Launches](launches) - Detailed info about launches
+
+### [Launchpads](launchpads) - Detailed info about launchpads
+
+### [Payloads](payloads) - Detailed info about launch payloads
+
+### [Roadster info](roadster) - Detailed info about Elon's Tesla roadster's current position
+
+### [Rockets](rockets) - Detailed info about rocket versions
+
+### [Ships](ships) - Detailed info about ships in the SpaceX fleet
+
+### [Starlink](starlink) - Detailed info about Starlink satellites and orbits
+
+Includes raw orbit data from [Space Track](https://www.space-track.org/auth/login), updated hourly.
+
+Space Track data adheres to the standard for [Orbit Data Messages](https://public.ccsds.org/pubs/502x0b2c1.pdf)
+
+### [History](history) - Detailed info on SpaceX historical events

docs/v4/capsules/all.md renamed to docs/capsules/v4/all.md

@@ -0,0 +1,27 @@
+## Changes from v4 -> v5
+
+* Crew is now an array of objects, to allow for more data on an individual launch for a crew member
+
+### Old Format
+
+```json
+{
+  "crew": [
+    "1234567890",
+    "123456789",
+    "123456789",
+  ]
+}
+```
+
+### New Format
+
+```json
+{
+  "crew": [
+    "1234567890",
+    "123456789",
+    "123456789",
+  ]
+}
+```

docs/v4/capsules/one.md renamed to docs/capsules/v4/one.md

@@ -0,0 +1,87 @@
+# Get all launches
+
+**Method** : `GET`
+
+**URL** : `https://api.spacexdata.com/v5/launches`
+
+**Auth required** : `False`
+
+## Success Responses
+
+**Code** : `200 OK`
+
+```json
+[
+    {
+        "fairings": null,
+        "links": {
+            "patch": {
+                "small": "https://images2.imgbox.com/53/22/dh0XSLXO_o.png",
+                "large": "https://images2.imgbox.com/15/2b/NAcsTEB6_o.png"
+            },
+            "reddit": {
+                "campaign": "https://www.reddit.com/r/spacex/comments/ezn6n0/crs20_launch_campaign_thread",
+                "launch": "https://www.reddit.com/r/spacex/comments/fe8pcj/rspacex_crs20_official_launch_discussion_updates/",
+                "media": "https://www.reddit.com/r/spacex/comments/fes64p/rspacex_crs20_media_thread_videos_images_gifs/",
+                "recovery": null
+            },
+            "flickr": {
+                "small": [],
+                "original": [
+                    "https://live.staticflickr.com/65535/49635401403_96f9c322dc_o.jpg",
+                    "https://live.staticflickr.com/65535/49636202657_e81210a3ca_o.jpg",
+                    "https://live.staticflickr.com/65535/49636202572_8831c5a917_o.jpg",
+                    "https://live.staticflickr.com/65535/49635401423_e0bef3e82f_o.jpg",
+                    "https://live.staticflickr.com/65535/49635985086_660be7062f_o.jpg"
+                ]
+            },
+            "presskit": "https://www.spacex.com/sites/spacex/files/crs-20_mission_press_kit.pdf",
+            "webcast": "https://youtu.be/1MkcWK2PnsU",
+            "youtube_id": "1MkcWK2PnsU",
+            "article": "https://spaceflightnow.com/2020/03/07/late-night-launch-of-spacex-cargo-ship-marks-end-of-an-era/",
+            "wikipedia": "https://en.wikipedia.org/wiki/SpaceX_CRS-20"
+        },
+        "static_fire_date_utc": "2020-03-01T10:20:00.000Z",
+        "static_fire_date_unix": 1583058000,
+        "tdb": false,
+        "net": false,
+        "window": 0,
+        "rocket": "5e9d0d95eda69973a809d1ec",
+        "success": true,
+        "failures": [],
+        "details": "SpaceX's 20th and final Crew Resupply Mission under the original NASA CRS contract, this mission brings essential supplies to the International Space Station using SpaceX's reusable Dragon spacecraft. It is the last scheduled flight of a Dragon 1 capsule. (CRS-21 and up under the new Commercial Resupply Services 2 contract will use Dragon 2.) The external payload for this mission is the Bartolomeo ISS external payload hosting platform. Falcon 9 and Dragon will launch from SLC-40, Cape Canaveral Air Force Station and the booster will land at LZ-1. The mission will be complete with return and recovery of the Dragon capsule and down cargo.",
+        "crew": [],
+        "ships": [],
+        "capsules": [
+            "5e9e2c5cf359185d753b266f"
+        ],
+        "payloads": [
+            "5eb0e4d0b6c3bb0006eeb253"
+        ],
+        "launchpad": "5e9e4501f509094ba4566f84",
+        "auto_update": true,
+        "flight_number": 91,
+        "name": "CRS-20",
+        "date_utc": "2020-03-07T04:50:31.000Z",
+        "date_unix": 1583556631,
+        "date_local": "2020-03-06T23:50:31-05:00",
+        "date_precision": "hour",
+        "upcoming": false,
+        "cores": [
+            {
+                "core": "5e9e28a7f359187afd3b2662",
+                "flight": 2,
+                "gridfins": true,
+                "legs": true,
+                "reused": true,
+                "landing_attempt": true,
+                "landing_success": true,
+                "landing_type": "RTLS",
+                "landpad": "5e9e3032383ecb267a34e7c7"
+            }
+        ],
+        "id": "5eb87d42ffd86e000604b384"
+    },
+    ...
+]
+```

docs/v4/capsules/query.md renamed to docs/capsules/v4/query.md

@@ -0,0 +1,84 @@
+# Get latest launch
+
+**Method** : `GET`
+
+**URL** : `https://api.spacexdata.com/v5/launches/latest`
+
+**Auth required** : `False`
+
+## Success Responses
+
+**Code** : `200 OK`
+
+```json
+{
+    "fairings": null,
+    "links": {
+        "patch": {
+            "small": "https://images2.imgbox.com/53/22/dh0XSLXO_o.png",
+            "large": "https://images2.imgbox.com/15/2b/NAcsTEB6_o.png"
+        },
+        "reddit": {
+            "campaign": "https://www.reddit.com/r/spacex/comments/ezn6n0/crs20_launch_campaign_thread",
+            "launch": "https://www.reddit.com/r/spacex/comments/fe8pcj/rspacex_crs20_official_launch_discussion_updates/",
+            "media": "https://www.reddit.com/r/spacex/comments/fes64p/rspacex_crs20_media_thread_videos_images_gifs/",
+            "recovery": null
+        },
+        "flickr": {
+            "small": [],
+            "original": [
+                "https://live.staticflickr.com/65535/49635401403_96f9c322dc_o.jpg",
+                "https://live.staticflickr.com/65535/49636202657_e81210a3ca_o.jpg",
+                "https://live.staticflickr.com/65535/49636202572_8831c5a917_o.jpg",
+                "https://live.staticflickr.com/65535/49635401423_e0bef3e82f_o.jpg",
+                "https://live.staticflickr.com/65535/49635985086_660be7062f_o.jpg"
+            ]
+        },
+        "presskit": "https://www.spacex.com/sites/spacex/files/crs-20_mission_press_kit.pdf",
+        "webcast": "https://youtu.be/1MkcWK2PnsU",
+        "youtube_id": "1MkcWK2PnsU",
+        "article": "https://spaceflightnow.com/2020/03/07/late-night-launch-of-spacex-cargo-ship-marks-end-of-an-era/",
+        "wikipedia": "https://en.wikipedia.org/wiki/SpaceX_CRS-20"
+    },
+    "static_fire_date_utc": "2020-03-01T10:20:00.000Z",
+    "static_fire_date_unix": 1583058000,
+    "tdb": false,
+    "net": false,
+    "window": 0,
+    "rocket": "5e9d0d95eda69973a809d1ec",
+    "success": true,
+    "failures": [],
+    "details": "SpaceX's 20th and final Crew Resupply Mission under the original NASA CRS contract, this mission brings essential supplies to the International Space Station using SpaceX's reusable Dragon spacecraft. It is the last scheduled flight of a Dragon 1 capsule. (CRS-21 and up under the new Commercial Resupply Services 2 contract will use Dragon 2.) The external payload for this mission is the Bartolomeo ISS external payload hosting platform. Falcon 9 and Dragon will launch from SLC-40, Cape Canaveral Air Force Station and the booster will land at LZ-1. The mission will be complete with return and recovery of the Dragon capsule and down cargo.",
+    "crew": [],
+    "ships": [],
+    "capsules": [
+        "5e9e2c5cf359185d753b266f"
+    ],
+    "payloads": [
+        "5eb0e4d0b6c3bb0006eeb253"
+    ],
+    "launchpad": "5e9e4501f509094ba4566f84",
+    "auto_update": true,
+    "flight_number": 91,
+    "name": "CRS-20",
+    "date_utc": "2020-03-07T04:50:31.000Z",
+    "date_unix": 1583556631,
+    "date_local": "2020-03-06T23:50:31-05:00",
+    "date_precision": "hour",
+    "upcoming": false,
+    "cores": [
+        {
+            "core": "5e9e28a7f359187afd3b2662",
+            "flight": 2,
+            "gridfins": true,
+            "legs": true,
+            "reused": true,
+            "landing_attempt": true,
+            "landing_success": true,
+            "landing_type": "RTLS",
+            "landpad": "5e9e3032383ecb267a34e7c7"
+        }
+    ],
+    "id": "5eb87d42ffd86e000604b384"
+}
+```

docs/v4/capsules/schema.md renamed to docs/capsules/v4/schema.md

@@ -0,0 +1,84 @@
+# Get next launch
+
+**Method** : `GET`
+
+**URL** : `https://api.spacexdata.com/v5/launches/next`
+
+**Auth required** : `False`
+
+## Success Responses
+
+**Code** : `200 OK`
+
+```json
+{
+    "fairings": null,
+    "links": {
+        "patch": {
+            "small": "https://images2.imgbox.com/53/22/dh0XSLXO_o.png",
+            "large": "https://images2.imgbox.com/15/2b/NAcsTEB6_o.png"
+        },
+        "reddit": {
+            "campaign": "https://www.reddit.com/r/spacex/comments/ezn6n0/crs20_launch_campaign_thread",
+            "launch": "https://www.reddit.com/r/spacex/comments/fe8pcj/rspacex_crs20_official_launch_discussion_updates/",
+            "media": "https://www.reddit.com/r/spacex/comments/fes64p/rspacex_crs20_media_thread_videos_images_gifs/",
+            "recovery": null
+        },
+        "flickr": {
+            "small": [],
+            "original": [
+                "https://live.staticflickr.com/65535/49635401403_96f9c322dc_o.jpg",
+                "https://live.staticflickr.com/65535/49636202657_e81210a3ca_o.jpg",
+                "https://live.staticflickr.com/65535/49636202572_8831c5a917_o.jpg",
+                "https://live.staticflickr.com/65535/49635401423_e0bef3e82f_o.jpg",
+                "https://live.staticflickr.com/65535/49635985086_660be7062f_o.jpg"
+            ]
+        },
+        "presskit": "https://www.spacex.com/sites/spacex/files/crs-20_mission_press_kit.pdf",
+        "webcast": "https://youtu.be/1MkcWK2PnsU",
+        "youtube_id": "1MkcWK2PnsU",
+        "article": "https://spaceflightnow.com/2020/03/07/late-night-launch-of-spacex-cargo-ship-marks-end-of-an-era/",
+        "wikipedia": "https://en.wikipedia.org/wiki/SpaceX_CRS-20"
+    },
+    "static_fire_date_utc": "2020-03-01T10:20:00.000Z",
+    "static_fire_date_unix": 1583058000,
+    "tdb": false,
+    "net": false,
+    "window": 0,
+    "rocket": "5e9d0d95eda69973a809d1ec",
+    "success": true,
+    "failures": [],
+    "details": "SpaceX's 20th and final Crew Resupply Mission under the original NASA CRS contract, this mission brings essential supplies to the International Space Station using SpaceX's reusable Dragon spacecraft. It is the last scheduled flight of a Dragon 1 capsule. (CRS-21 and up under the new Commercial Resupply Services 2 contract will use Dragon 2.) The external payload for this mission is the Bartolomeo ISS external payload hosting platform. Falcon 9 and Dragon will launch from SLC-40, Cape Canaveral Air Force Station and the booster will land at LZ-1. The mission will be complete with return and recovery of the Dragon capsule and down cargo.",
+    "crew": [],
+    "ships": [],
+    "capsules": [
+        "5e9e2c5cf359185d753b266f"
+    ],
+    "payloads": [
+        "5eb0e4d0b6c3bb0006eeb253"
+    ],
+    "launchpad": "5e9e4501f509094ba4566f84",
+    "auto_update": true,
+    "flight_number": 91,
+    "name": "CRS-20",
+    "date_utc": "2020-03-07T04:50:31.000Z",
+    "date_unix": 1583556631,
+    "date_local": "2020-03-06T23:50:31-05:00",
+    "date_precision": "hour",
+    "upcoming": false,
+    "cores": [
+        {
+            "core": "5e9e28a7f359187afd3b2662",
+            "flight": 2,
+            "gridfins": true,
+            "legs": true,
+            "reused": true,
+            "landing_attempt": true,
+            "landing_success": true,
+            "landing_type": "RTLS",
+            "landpad": "5e9e3032383ecb267a34e7c7"
+        }
+    ],
+    "id": "5eb87d42ffd86e000604b384"
+}
+```