Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Is GraphQL really self-documenting?

James Scott
November 09, 2018

Is GraphQL really self-documenting?

A conference talk discussing whether GraphQL is self-documenting.

Discusses self-documenting code, the origins of GraphQL, the importance of naming and descriptions in GraphQL and how you can document it.

Location: API the Docs at the Barbican Centre in London.

James Scott

November 09, 2018
Tweet

More Decks by James Scott

Other Decks in Technology

Transcript

  1. “A common mistake people make when trying to design something

    completely foolproof is to underestimate the ingenuity of complete fools.” - Douglas Adams @jwscott22
  2. 1. What is the problem? 
 2. What is GraphQL?


    3. What is the answer? Agenda @jwscott22
  3. What does “self-documenting” mean? Written and structured in such a

    way it can be understood without documentation or prior-knowledge. @jwscott22
  4. @jwscott22 Subjectivity with words query{ second } query{ number }

    query{ subject } 1. Numerical value 2. A quantity or amount 3. To count (verb) 4. More numb 1. Topic 2. The noun in a sentence 3. Under some authority 1. Unit of time 2. Number 2 in a sequence
  5. 1. I made an object/function with a specific use 2.

    I gave it a name that explains the specific use 3. Doesn’t need docs because it’s obvious how it works. @jwscott22 What it boils down to…
  6. 1. What is the problem? 
 2. What is GraphQL?


    3. What is the answer? Agenda @jwscott22
  7. “…I think the biggest mistake we made as a company

    is betting too much on HTML5 as opposed to native… because it just wasn’t there… We burned two years. That's really painful.” - Mark Zuckerberg, Facebook CEO Origins of GraphQL @jwscott22
  8. Founders of GraphQL Lee Byron Nick Schrock Dan Schafer Mobile

    app dev team lead Creator of SuperGraph Facebook News Feed engineer
  9. GraphQL at Facebook iOS News Feed iOS Messenger Ads Manager

    Facebook Lite iPad Pages Android Feed @jwscott22
  10. So what is GraphQL? • Data query language for APIs

    • Can retrieve data using a query • Can modify data using a mutation • Client specifies exact data they want • Result is no over-fetching of data • Exposes a single endpoint to do all of these things. @jwscott22
  11. A Graph = A Tree @jwscott22 Member Book “Frodo” “Sam”

    “Pippin” “Merry” “Aragorn” “Boromir” “Gimli” “Legolas” “Gandalf” Hobbit Man Dwarf Elf Istari Man Hobbit Hobbit Hobbit “The Fellowship of the Ring” title inFellowship race race race race race race race race race name name name name name name
  12. What does GraphQL look like? @jwscott22 { hero { name

    } } { "data" : { "hero" : { "name" : "Frodo" } } }
  13. Query to return related objects @jwscott22 { hero { name

    companion { name } } } { "data" : { "hero" : { "name" : "Frodo", "companion" : [ { "name" : "Sam" }, { "name" : "Gandalf" }, { "name" : "Legolas" }, { "name" : "Gimli" }, { "name" : "Aragorn" }, { "name" : "Merry" }, { "name" : "Pippin" } ] } } }
  14. Over-fetching @jwscott22 $ curl https://localhost/lotr/v1/getInfo?characterid=6 [ { "character":{ "name":"Aragorn", "alias":"Strider",

    "title":"King of the Reunited Kingdom", "height":"1.98", "house":"Telcontar", "weapon":"Anduril", "race":"Human", "gender":"Male", "age":"210", "wife":"Arwen", "father":"Arathorn", "mother":"Gilraen", } } ]
  15. Query using arguments @jwscott22 { character(id:"6") { name height age

    } } { "data" : { "character" : { "name" : "Aragorn" "height" : 1.98 "age" : 210 } }
  16. GraphQL mutations @jwscott22 mutation { addCategory( id:1, name: "hobbits", characters:

    [1, 2, 7, 8]) { name characters { name } } } { "data" : { "addCategory": { "name": "hobbits", "characters": [ { "name": "Frodo" }, { "name": "Sam" }, { "name": "Merry" }, { "name": "Pippin" } ] } } }
  17. GraphiQL (“Graphical”) @jwscott22 Imagine landing here with no prior knowledge

    of: • What the schema looks like • How to structure a query • What queries are even possible!
  18. @jwscott22 query { user { jwscott22 { name } }

    } { "data" : null, "errors": [ { "message": "Field 'user' is missing required arguments: login", "locations": [ { "line": 2, "column": 3} ] }, { "message": "Field 'jwscott22' doesn't exist on type 'User'", "locations": [ { "line": 3, "column": 5} ] } ] } query { user(login:jwscott22) { name avatarUrl location } } }
  19. 1. What is the problem? 
 2. What is GraphQL?


    3. What is the answer? Agenda @jwscott22
  20. @jwscott22 “Naming things that adhere closely to what those things

    do is really important to make this experience work…”
  21. Hi Lee, I’m writing a blog about GraphQL. Could I

    ask you some questions over video chat at some point? James Hi James! Sorry for the delay. I’d be happy to do an interview with you. Lee @jwscott22
  22. - Lee Byron, co-creator of GraphQL “If there's no documentation,

    it doesn't matter how good the API is […] If you do that wrong, people aren't going to be able to use it…” @jwscott22
  23. Filling the “clear space” Constant FilmTYpe = new GraphQLObjectType({ name:

    'Film', description: 'A single film.', fields: () => ( { title: { type: GraphQLString, description: 'The title of this film.', }, episodeID: { type: GraphQLInt, description: 'The episode number of this film.', }, openingCrawl: { type: GraphQLString, description: ‘The opening paragraphs at the beginning of this film.', }, director: { type: GraphQLString, description: ‘The name of the director of this film.', }, @jwscott22
  24. GraphiQL Docs Features 1. Inline descriptions 2. Autocomplete 3. Hover

    tool-tips 4. (⌥ + Space) 5. Introspection 6. Docs Explorer
  25. What do other tech writers say? @jwscott22 “… we thought

    that it was important to have educational stuff and hand-holding material to introduce people to GraphQL… …you don’t want to just assume that people know how to formulate queries and mutations…” - Andrew Johnston “Documenting API endpoints explains how individual tools work,
 
 explaining how to use those tools together is a whole other area of documentation effort. …” - Chris Ward
  26. Documenting GraphQL @jwscott22 1. Generic docs: • On-boarding/hand-holding docs on

    basics. 2. API specific docs: • Provide query and mutation examples. • Supporting docs for specific use cases. 3. In the API itself: • Choose appropriate names for your fields/types. • Use good descriptions in the schema.
  27. @jwscott22 The end? “I didn’t think it would end this

    way.” “End? No, the journey doesn’t end here.”
  28. • “My Code is Self-documenting” - Eric Holcher http://ericholscher.com/blog/ 2017/jan/27/code-is-self-documenting/

    • “Why you should document your self-documenting code - Oleksandr Kaleniuk - https://hackernoon.com/why-you-should-document-your-self- documenting-code-1105a8a6852e • Lessons from 4 Years of GraphQL (Lee Byron speaking at GraphQL Summit 2016) https://www.youtube.com/watch?v=zVNrqo9XGOs • “Does GraphQL reduce the need for documentation?” - Chris Ward @ChrisChinch https://blog.codeship.com/documenting-graphql/ • Documenting GraphQL at Shopify - Andrew Johnston @andrewjtech https:// www.youtube.com/watch?v=uuzsEfLaGnU&feature=youtu.be • Life is Hard and so is learning GraphQL - Carolyn Stransky @carolstran https://youtu.be/FsRSdGuj588 Resources & Further Reading @jwscott22
  29. • “self-documenting code” definition PC Magazine: https:// www.pcmag.com/encyclopedia/term/51077/self-documenting-code • The

    latest GraphQL spec: https://facebook.github.io/graphql/ June2018/ • Interview with GraphQL co-creator Lee Byron: https://nordicapis.com/ interview-with-graphql-co-creator-lee-byron/ • Repo of public GraphQL API docs and tools: https://github.com/ Jwscott22/GraphQL-docs • An extensive list of public GraphQL APIs: https://github.com/APIs- guru/graphql-apis • Who’s Using GraphQL - https://graphql.org/users/ Other Resources
  30. • Image:Pair-Program-Step-3-Version-2.jpg - © Creative Commons • Hitchhikers Guide to

    the Galaxy - © Touchstone Pictures • Gollum from the Two Towers (2002) - Warner Bros • Art of Programming - © Geek and Poke • Unicorn from Blade Runner (1982) - © Warner Bros • Screenshot of Lessons from 4 Years of GraphQL - Apollo GraphQL • Success Kid - Wikimedia Commons • Pokemon Group - © Pokemon Company International Inc. • Magnifying Glass - © KissPNG.com • Robot Emoji- © emojiisland.com Media Copyright