Giter Club home page Giter Club logo

graphql.github.io's Introduction

Source Repository for graphql.org

This repository contains the source code for the GraphQL website.

You can find more discussions on the #website channel on the GraphQL Slack. Get your invite here!

A brief overview: GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. It provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need, and enables powerful developer tools. The specification is open source and governed by the GraphQL Foundation.

Documentation

Deployment

The site is deployed via Netlify on merges to the source branch, you can see the builds here.

How to contribute

Check out our contributing guide for detailed instructions on how to make changes to the GraphQL website ๐ŸŽ‰

This repository is managed by EasyCLA. Project participants must sign the free (GraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers.

To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.

You can find detailed information here. If you have issues, please email [email protected].

If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the GraphQL Foundation.

graphql.github.io's People

Contributors

acao avatar ardatan avatar babyfish-ct avatar beerose avatar benjie avatar brianwarner avatar caniszczyk avatar carolstran avatar cometkim avatar dimamachina avatar dschafer avatar gsans avatar lacker avatar leebyron avatar leoloso avatar michaelstaib avatar nikolasburk avatar olegilyenko avatar orta avatar praveenweb avatar renovate-bot avatar renovate[bot] avatar robzhu avatar setchy avatar tuvalsimha avatar urigo avatar vning93 avatar wincent avatar yassineldeeb avatar zpao avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

graphql.github.io's Issues

Figure out a schema for all query examples

That way, we can set up all of the examples with the interactive query editor, instead of having static code snippets. But we need to make sure the schema has all of the features we want to demonstrate. Opening the issue here to keep track of this need.

Transfer of graphql.training

Hi!

I'm presently the owner of graphql.training (and its respective github organisation, @GraphQL-Training). I'd like to transfer this domain across to the GraphQL Community, as I have no real use for it (context)

I've tried to get in contact with people from the community in the past, but to no responses other than likes on twitter. If I don't find an entity to transfer the domain to, I'll likely just let it lapse at the end of it's current registration period, but that'd mean it'd likely be picked up by someone with the community's best interests not at heart.

If you see this and you're a company, you're welcome to pitch an idea either publicly or privately (email's on my github profile or website)

printable docs

Hello,
I'd like to print myself a handbook, but the layout of the docs is making this somewhat difficult. I forked and managed to get rid of the sidebar, but each section tag is limited to one page- so even if try to make a PDF of a really long page, I get exactly three pages: one for the header, one for the truncated body, and one for the footer. Can someone please fix this?

Super feature request: one-page version of the docs. For now, I'll just manually merge the markdown files.

Todos for learn section

  • Cover __typename
  • Cover non-root field arguments in queries
  • Cover input objects
  • Defining operations for arguments
  • Default values for arguments
  • Convert index.html to match new schema

how to config algolia

we forked this repo and translate it into chinese.

algolia has already setup. index has been added. but cannot get search result.

is there anything must be config?

operationName is hard to grasp

The current section about operation names, here: http://graphql.org/learn/queries/#operation-name
reads like this:

One thing we also saw in the example above is that our query has acquired an operation name. Up until now, we have been using a shorthand syntax where we omit both the query keyword and the query name, but in production apps it's useful to use these to make our code less ambiguous.

Think of this just like a function name in your favorite programming language. For example, in JavaScript we can easily work only with anonymous functions, but when we give a function a name, it's easier to track it down, debug our code, and log when it's called. In the same way, GraphQL query and mutation names, along with fragment names, can be a useful debugging tool on the server side to identify different GraphQL requests.

The problem is that after reading this section there is no example or other hint on the shape in which the operation's name should be specified or where to look up the spec. It would be nice to be pointed to somewhere in this section.

Aside from that: Thank you for your great work!

documentation should include `__resolveType` requirement for Union Type to return interface

There's no mention in the documentation that Union Types require a __resolveType field in the Resolver for the Union.

a good example of helpful information can be found at Apollo's Documentation

When you have a field in your schema that returns a union or interface type, you will need to specify an extra __resolveType field in your resolver map, which tells the GraphQL executor which type the result is, out of the available options.

Human Type under interfaces

Steps to reproduce:
Visit: http://graphql.github.io/learn/schema/

Under Interfaces where we have

... on Droid {
      primaryFunction
    }

add

... on Human {
      totalCredits
     }

After that, change totalCredits to height and the error goes away.

screen shot 2018-08-15 at 1 54 05 pm 2

screen shot 2018-08-15 at 1 54 17 pm 2

This is probably happening because this query is using the type 'Human' from one of the previous pages that have the field height

Extend Versioning paragraph in Best Practises

The Versioning in the Best Practises section is explaining why traditional REST APIs need Versioning to deal with breaking changes. But later sentences don't explain what are the best practises with GraphQL do deal with breaking changes. For example how should I handle the case when I want to remove or rename a field of a type?

Infinite redirection loop at graphql.org

The page seems to be redirecting in an infinite loop between the HTTP and HTTPS version

$ wget http://graphql.org/index.html 
--2018-05-27 14:29:13--  http://graphql.org/index.html
Resolving graphql.org (graphql.org)... 54.192.7.25, 2600:9000:2008:da00:5:5ca6:5c40:93a1
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:13--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:15--  http://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:16--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:17--  http://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:18--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:20--  http://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:21--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:22--  http://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:23--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:25--  http://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:80... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: https://graphql.org/index.html [following]
--2018-05-27 14:29:25--  https://graphql.org/index.html
Connecting to graphql.org (graphql.org)|54.192.7.25|:443... connected.
HTTP request sent, awaiting response... 301 Moved Permanently
Location: http://graphql.org/index.html [following]
--2018-05-27 14:29:27--  http://graphql.org/index.html

graphql.js custom scalar type docs are very vague

I was trying to create a custom scalar type by reading the docs, but what's there is very vague and confusing:

  • What are the semantics of the three required functions? Only names are listed right now.
  • The example doesn't compensate for the lack of descriptions, since it uses the same function for two of the fields
  • The example type is strange: it... returns the value if odd and null otherwise? That seems like a completely fanciful type with no practical use. Perhaps a Date type would be more useful?

I think the GraphQL docs are fantastic overall, but this section was not clear at all.

GraphQL Union and Interface Example - help needed

I am looking for an example on GraphQL Union and Interface. Appreciate if any one can help by providing an example or link that shows how to define a query and resolvers for Union and Interface. Thanks and regards, Ram

For translation

Can I translate this documents to korean on this blog or cloned repository?

List public GraphQL APIs on website

... aka "enough about Star Wars". ;-)

I want to know about real-world GraphQL APIs, which can hopefully inspire my own API design and demonstrate best practices.

Facebook, and indeed most of the companies on the "Whoโ€™s using GraphQL?" page, seem to only use it internally, and that's great for them but doesn't really teach me anything. GitHub has a publicly documented API. Are there others?

If so, it might be helpful to separate that page into "companies with public APIs" (and link to API docs) and "companies using it internally".

Add graphql-tools reference to GraphQL.js tutorial

Right now a lot of people are running into confusion with the buildSchema approach in the getting started guide, there are a few things that are confusing about it:

  1. The root object isn't the same as the usual resolvers. Resolvers have a signature of (root, args, context), but with the rootValue object instead you get (args, context).
  2. You get stuck as soon as you need interfaces or unions. SO question that reminded me here.
  3. There isn't a clear way to scale up to multiple files.

For a bit over a year we've had the graphql-tools package which addresses exactly these concerns but doesn't introduce any additional opinions: http://dev.apollodata.com/tools/graphql-tools/generate-schema.html

It would be pretty much a drop-in replacement for buildSchema in the tutorial, would be happy to make the switch if people think this could be a good idea.

Here's an example of how the code would change:

With buildSchema, currently

var { graphql, buildSchema } = require('graphql');

// Construct a schema, using GraphQL schema language
var schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// The root provides a resolver function for each API endpoint
var root = {
  hello: () => {
    return 'Hello world!';
  },
};

// Run the GraphQL query '{ hello }' and print out the response
graphql(schema, '{ hello }', root).then((response) => {
  console.log(response);
});

With graphql-tools

var { graphql } = require('graphql');
var { makeExecutableSchema } = require('graphql-tools');

// Construct a schema, using GraphQL schema language
var typeDefs = `
  type Query {
    hello: String
  }
`;

// The provide a resolver function for each query field
var resolvers = {
  hello: () => {
    return 'Hello world!';
  },
};

var schema = makeExecutableSchema({
  typeDefs: typeDefs,
  resolvers: resolvers
});

// Run the GraphQL query '{ hello }' and print out the response
graphql(schema, '{ hello }').then((response) => {
  console.log(response);
});

Also looking at that snippet there are some oddities like the text "resolver function for each API endpoint", which I'd be happy to fix while I'm there.

[New-Source] Missing hrefs in Learn landing page

Most of the links in the table of contents at https://github.com/graphql/graphql.github.io/blob/new-source/site/learn/index.html.js are missing hrefs:

            <ul>
              <li><a>Query Language</a></li>
              <li><a>Type System</a></li>
              <li><a>Validation</a></li>
              <li><a>Execution</a></li>
              <li><a>Introspection</a></li>
            </ul>
            <ul>
              <li><a href="/learn/serving-over-http/">Serving Over HTTP</a></li>
              <li><a href="/learn/authorization/">Authorization</a></li>
              <li><a>Domain Modeling</a></li>
              <li><a>Pagination</a></li>
              <li><a>Versioning</a></li>
              <li><a>Performance</a></li>
              <li><a>Security</a></li>

This page is linked to from the "Learn" navigation item in the header.

Confused about how to merge fields in field selection

Currently the GrapgQL spec at https://facebook.github.io/graphql/#sec-Field-Selection-Merging only mention conditions that have to apply in order for fields in a selection to merge. While discussing a fix to an issue ( youshido-php/GraphQL#138 ) the specification was brought up.

It is pretty confusing to infer how to actually merge fields in a selection just from the specs alone, because they only seem to be talking about how to know when multiple fields can merge, and not about how to actually do the merging.

Can we get some more specific documentation on how to merge fields? Can we get some examples of how to merge fields of object types and array types?

Resolver parameter order documented incorrectly

According to the documentation, resolver functions are written as follows:

function someField(obj, args, context) {
  // Return something...
}

However, when I build resolver functions, the parameters provided by GraphQL are

  • args
  • context
  • obj

So I end up having to build resolvers as follows:

function someField(args, context, obj) {
   // Return something...
}

My understanding of these parameters is as follows:

  • obj - the parent object, if any
  • args - contains the arguments passed to the field in the query (e.g. when executing the query query { someField(foo: "bar") }, args is set to {foo: 'bar'}
  • context - the object provided as the 4th parameter to the graphql function

Am I missing something or are is the documentation incorrect?

Easier navigation to graphql-js tutorial

The entire section of http://graphql.org/graphql-js/ which contain the node.js tutorials isn't mentioned in the header or the footer of graphql.org. I think that's a shame since this section is very well written and frankly pure gold for anyone implementing with node.js.

I could only find links to the page though http://graphql.org/code/ and it's not that clear in there you're going to see a thorough tutorial. I think a link at least at the footer could be beneficial.

I found it only by googling.

I'll add that https://github.com/graphql/graphql-js readme clearly refers to this documentation.
references https://github.com/graphql/express-graphql readme file are a little more obscure.

Missing mutation result type in the doc "Mutations and Input Types"

Referred doc: http://graphql.org/graphql-js/mutations-and-input-types/
Source: https://github.com/graphql/graphql.github.io/blob/c22ba1a/site/graphql-js/Tutorial-Mutations.md

The result type of createMessage and updateMessage is missing in the schema and the "runnable code" example.
I was expecting the doc to specify the result of mutation types -- a simple boolean that indicates success/fail of the mutation? or just return the newly updated message instance?

Although it may not be the main concern of the article "Mutations and Input Types", but some insights on the design of return type of mutations would be great.

Documentation about adding a mutation was hard to follow

I was looking into how to add a "Create User" mutation to my graphql-js server. It took me a while to end up at the right code, so just documenting where I got confused:

  1. Searched for "Mutation" on the site. There are two sections ostensibly about mutation:
    a. http://graphql.org/learn/queries/#mutations
    b. http://graphql.org/learn/schema/#the-query-and-mutation-types
  2. Skimming each page, it was hard to figure out how to actually define a mutation in the schema. The code talking about mutations wasn't clear if it was showing how to do them in the query or in the schema.
  3. I found the operative sentence is in (b): "Mutations work in a similar way - you define fields on the Mutation type, and those are available as the root mutation fields you can call in your query." and was able to write the correct schema:
  input CreatePersonInput {
    name: String
  }
  type Mutation {
    createPerson(person: CreatePersonInput!): Person
  }

Suggestions:

  • I was thinking it would be better to just put an example of the schema changes necessary to make a mutation right into the schema (b) section to avoid confusion
  • Make it clearer when a block of code in the docs is in GraphQL query language or schema language (maybe even show "Query" and "Response" labels next to the left and right sides)

Pagination alternative

Merry christmas everyone ๐ŸŽ

Here's an alternative to the recommended approach regarding pagination.

type Query {
  allPeople(first: Int = 0, after: String = ""): [Person]
  allPeoplePage: PageInfo!
}

type PageInfo {
  nextCursor: String
  prevCursor: String
  startCursor: String
  endCursor: String
  cursors: [String]
  totalCount: Int
}

The idea is a basic convention: Any list field x may have pagination info at xPage. hasNextPage/hasPrevPage would be nextCursor/prevCursor !== null, respectively.
cursors would hold a list of cursors aligned to the returned items.

Pros:

  • Much less types. For example, no PersonConnection, no PersonEdge, etc.
  • Data structure is not dictated by "has to support pagination (or not)"
  • Orthogonal: We can evolve from "pagination for x not supported" to "x can now be paginated by requesting xPage" without breaking x or introducing "pagedX { edges: { node: { name } } pageInfo: { ... } }"
  • Shallow data is easier to consume

Cons:

  • Cannot add edge-specific information like "friendship time". You'll have to introduce a "Friendship" thing in that case anyway, though.
  • Data-wise, cursors are only indirectly coupled with their items (by index)

What do you think? If it could be useful to the community, I'd be happy to write it up for graphql.org. I'm looking to use this pattern next year and come back with real-world feedback.

Cheers

none of the example can be run on standard graphiql

I tryed to past them in http://graphql.org/swapi-graphql and non of them worked. Why ? Is that not the obvious thing to do? examples from starwars. Here is a star wars standard simple hello world api. No none of the examples can be used to experiment with. "message": "Cannot query field "hero" on type "Root". Did you mean "person"?". This is supposed to be a fun intro to GraphQl not a sudoku puzzle

Is this being maintained?

Beyond being just an informative site, there are pull requests since November of last year. Can I help with this?

BSD or MIT

I visited the website and to my surprise I saw this

Copyright ยฉ2017 Facebook Inc. The contents of this page are licensed BSD-3-Clause.

Graphql-js is MIT but when I read the docs I see as above. I almost submitted a PR but then I checked the graphql repo and found out some projects are licensed MIT while others are BSD.

Did you do it on purpose? I'm a little confused

[Master] New graphql.org

This is a master task for all the various work necessary for the graphql.org relaunch with inline assignees by page.

  • /index.html * @leebyron
  • /learn/
    • Core Concepts
    • Best Practices
      • learn/domain-modeling/ @robzhu
      • learn/serving-over-http/ * @robzhu
      • learn/authorization/ * @robzhu
      • learn/pagination/
      • learn/versioning/ *
      • learn/performance/
      • learn/security/
      • learn/design-guidelines/
      • learn/using-variables/
      • learn/colocated-queries/
      • learn/client-caching/ *
      • learn/persisted-queries/
      • learn/code-generation/
      • learn/migrating-from-rest/
  • /code/ * @lacker
  • /community/ * @theadactyl
    • Links out to places for help
    • Calendar of upcoming events
    • Grid of conference talks
  • /blog/ @leebyron

* indicates a goal for content complete by relaunch day (Sept 13th), though all content should be completed in Q3 (these are open to change).

[documentation] Possibly incorrect example in pagination docs

I'm just getting familiar with GraphQL, so forgive me if I'm missing something. But I found the following snippet confusing in the documentation on pagination.

"our friends field should give us a list of edges, and an edge has both a cursor and the underlying node:"

...but in the associated example, the GraphQL request does not mention edges:

{
  hero {
    name
    friends(first:2) {
      node {
        name
      }
      cursor
    }
  }
}

Should the example be something like this?:

{
  hero {
    name
    friends(first:2) {
      edges {
        node {
          name
        }
        cursor
      }
    }
  }
}

Btw many thanks for releasing this impressive library!

Set up automatic GraphiQL-ization of code snippets

Ideally, you can just write markdown code snippets, and they will get converted to interactive editors automatically. That way, you can still read the files in markdown format.

This means we need a way to tag which ones need to be interactive, since the schema examples probably won't be.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.