Revamp/graphql section

content/dql-syntax/dql-rdf.md

@@ -78,7 +78,7 @@ The supported [RDF datatypes](https://www.w3.org/TR/rdf11-concepts/#section-Data
 | <http://www.w3.org/2001/XMLSchema#float>            | `float`          |
 
 
-<<<<<<<< HEAD:content/dql-syntax/dql-rdf.md
+
 
 
 ### Facets
@@ -125,6 +125,3 @@ Result:
   }
 }
 ```
-========
-See the section on [RDF schema types]({{< relref "predicate-types.md#rdf-types" >}}) to understand how RDF types affect mutations and storage.
->>>>>>>> main:content/mutations/language-rdf-types.md

content/graphql/_index.md

@@ -24,7 +24,7 @@ description = "Generate a GraphQL API and a graph backend from a single GraphQL
   </div>
   <div class="item">
     <div class="icon"><i class="lni lni-layout" aria-hidden="true"></i></div>
-    <a href="{{< relref "schema/schema-overview.md">}}">
+    <a href="{{< relref "schema">}}">
       <h2>Schema</h2>
       <p>
         All the things that you can put in your input GraphQL schema
@@ -33,7 +33,7 @@ description = "Generate a GraphQL API and a graph backend from a single GraphQL
   </div>
   <div class="item">
     <div class="icon"><i class="lni lni-cloud-network" aria-hidden="true"></i></div>
-    <a href="{{< relref "api/api-overview.md">}}">
+    <a href="{{< relref "api">}}">
       <h2>API</h2>
       <p>
         How to use the GraphQL API

content/graphql/api/_index.md

@@ -1,7 +1,23 @@
 +++
-title = "API"
+title = "Client API"
 [menu.main]
   identifier = "api"
   parent = "graphql"
-  weight = 5
-+++
+  weight = 8
++++
+
+How to use the GraphQL API. 
+
+Dgraph serves [spec-compliant
+GraphQL](https://graphql.github.io/graphql-spec/June2018/) over HTTP to two endpoints: `/graphql` and `/admin`. 
+
+
+In Dgraph Cloud `/graphql` and `/admin` are served from the domain of your backend, which will be something like `https://YOUR-SUBDOMAIN.REGION.aws.cloud.dgraph.io`. If you are running a self-hosted Dgraph instance that will be at the alpha port and url (which defaults to `http://localhost:8080` if you aren't changing any settings).
+
+In each case, both GET and POST requests are served.
+
+- `/graphql` is where you'll find the GraphQL API for the types you've added. That is the single GraphQL entry point for your apps to Dgraph.
+
+- `/admin` is where you'll find an admin API for administering your GraphQL instance. That's where you can update your GraphQL schema, perform health checks of your backend, and more.
+
+This section covers the API served at `/graphql`. See [Admin](/graphql/admin) to learn more about the admin API.

content/graphql/custom/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Custom Resolvers"
-weight = 9
+weight = 6
 [menu.main]
   identifier = "custom"
   parent = "graphql"

content/graphql/federation/index.md

@@ -1,7 +1,7 @@
 +++
 title = "Apollo Federation"
 description = "Dgraph now supports Apollo federation so that you can create a gateway GraphQL service that includes the Dgraph GraphQL API and other GraphQL services."
-weight = 14
+weight = 12
 [menu.main]
   name = "Apollo Federation"
   identifier = "federation"

content/graphql/lambda/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Lambda Resolvers"
-weight = 9
+weight = 7
 [menu.main]
   identifier = "lambda"
   parent = "graphql"

content/graphql/mutations/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Mutations"
-weight = 8
+weight = 4
 [menu.main]
   identifier = "graphql-mutations"
   parent = "graphql"

content/graphql/queries/_index.md

@@ -1,6 +1,6 @@
 +++
 title = "Queries"
-weight = 7
+weight = 3
 [menu.main]
   identifier = "graphql-queries"
   parent = "graphql"

content/graphql/quick-start/index.md

@@ -8,8 +8,10 @@ weight = 2
   parent = "graphql"
 +++
 
-Go from an empty Dgraph database to a running GraphQL API in just one step!  
-Just define the schema of your graph and how you’d like to search it; Dgraph does the rest.
+You might be familiar with GraphQL types, fields and resolvers.  Perhaps you've written an app that adds GraphQL over a REST endpoint or maybe over a relational database.  If so, you know how GraphQL sits over those sources and issues many queries to translate the REST/relational data into something that looks like a graph.  
+
+There's none of that with Dgraph : you can generate a running GraphQL API with the associated graph backend just by dpeloying the GraphQL schema of your API; Dgraph does the rest.
+
 
 ## Prerequisite : Run Dgraph
 

content/graphql/schema/_index.md

@@ -3,5 +3,13 @@ title = "Schema"
 [menu.main]
   identifier = "schema"
   parent = "graphql"
-  weight = 6
-+++
+  weight = 2
++++
+
+This section describes all the things you can put in your input GraphQL schema, and what gets generated from that.
+
+The process for serving GraphQL with Dgraph is to add a set of GraphQL type definitions using the `/admin` endpoint.  Dgraph takes those definitions, generates queries and mutations, and serves the generated GraphQL schema.  
+
+The input schema may contain interfaces, types and enums that follow the usual GraphQL syntax and validation rules. 
+
+If you want to make your schema editing experience nicer, you should use an editor that does syntax highlighting for GraphQL.  With that, you may also want to include the definitions [here](/graphql/schema/dgraph-schema) as an import.