Copy changes and GraphQL example
@@ -24,18 +24,34 @@ Using a human readable query language makes it obvious exactly what the satellit
Why GraphQL?
------------
-GraphQL gives the user more control over the endpoint, rather than dictating what every interaction entails.
+GraphQL gives callers more control over how they fetch data. Where REST exposes the business domain as URL-addressable resources that clients fetch as needed, **GraphQL models the domain as graph of fields** (sometimes with arguments) that may be fetched in a single query.
-For example, say a mission application needs to quickly get the current status of a single power port on a module to check if a payload is powered. For a ReST endpoint, a separate GET would be required to be availabe with just that single telemetry item. Now say there are 15 different power ports, and those assignments can change depending on the payload configuration.
+For example, say a mission application needs to quickly get the current status of a single power port on a module to check if a payload is powered. For a ReST endpoint, a separate GET would be required to be available with just that single telemetry item. Now say there are 15 different power ports, and those assignments can change depending on the payload configuration.
- - REST GET
+```
+GET api.kubos.com/m/1/s/1/power/1
+```
For each port, the endpoint would have to change to accommodate the individual request, adding a new request for any subset of telemetry they want retrieved. If a combination of 2 or more is required, it would have to be done in separate transactions.
- - REST GET 1
- - REST GET 2
- - REST GET 3
-
-With GraphQL, it's only a single query. The mission application is simplified to only ever be a single query and the endpoint doesn't have to add queries to accommodate each change in configuration.
-
- - GraphQL query
+```
+GET api.kubos.com/m/1/s/1/power/1
+GET api.kubos.com/m/1/s/1/power/2
+GET api.kubos.com/m/1/s/1/power/3
+...
+GET api.kubos.com/m/1/s/1/power/15
+```
+
+With GraphQL, it's a single query. The mission application is simplified and the endpoint doesn't have to add queries to accommodate each change in configuration.
+
+```
+query {
+ missions(id: "1") {
+ satellites(id: "1") {
+ power {
+ ...powerFields
+ }
+ }
+ }
+}
+```
