Pro Yearly is on sale from $80 to $50! »

Is GraphQL really self-documenting?

F4004183ff78e0cf67bb6e8a7d469702?s=47 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.

F4004183ff78e0cf67bb6e8a7d469702?s=128

James Scott

November 09, 2018
Tweet

Transcript

  1. Is GraphQL really self-documenting? James Scott Technical Writer at Moogsoft

    @jwscott22
  2. @jwscott22

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

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


    3. What is the answer? Agenda @jwscott22
  5. @jwscott22

  6. What does “self-documenting” mean? Written and structured in such a

    way it can be understood without documentation or prior-knowledge. @jwscott22
  7. Subjectivity with images @jwscott22

  8. @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
  9. @jwscott22 “Self-documenting code is a unicorn”

  10. @jwscott22 Others have said similar…

  11. 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…
  12. 1. What is the problem? 
 2. What is GraphQL?


    3. What is the answer? Agenda @jwscott22
  13. “…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
  14. Founders of GraphQL Lee Byron Nick Schrock Dan Schafer Mobile

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

    Facebook Lite iPad Pages Android Feed @jwscott22
  16. Relay GraphQL @jwscott22 Open-sourcing of GraphQL

  17. @jwscott22

  18. 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
  19. Thinking in Graphs @jwscott22 Graph theory!?

  20. 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
  21. What does GraphQL look like? @jwscott22 { hero { name

    } } { "data" : { "hero" : { "name" : "Frodo" } } }
  22. 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" } ] } } }
  23. 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", } } ]
  24. Query using arguments @jwscott22 { character(id:"6") { name height age

    } } { "data" : { "character" : { "name" : "Aragorn" "height" : 1.98 "age" : 210 } }
  25. 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" } ] } } }
  26. 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!
  27. @jwscott22

  28. @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 } } }
  29. Scenario 1: Assumed Knowledge! @jwscott22

  30. @jwscott22 Scenario 2: ‘Self descriptive’?

  31. 1. What is the problem? 
 2. What is GraphQL?


    3. What is the answer? Agenda @jwscott22
  32. <Insert_sensible_name> “Naming is Super Important…” @jwscott22 “Would a new engineer

    understand this?”
  33. @jwscott22 “Naming things that adhere closely to what those things

    do is really important to make this experience work…”
  34. What does the spec say? @jwscott22

  35. 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
  36. @jwscott22 Advice from the co-creator

  37. - 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
  38. 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
  39. GraphiQL Docs Features 1. Inline descriptions 2. Autocomplete 3. Hover

    tool-tips 4. (⌥ + Space) 5. Introspection 6. Docs Explorer
  40. Other GraphQL tools @jwscott22

  41. Not very human…. @jwscott22 “…an unhealthy reliance on the self-documenting

    aspects of GraphQL …” - Carolyn Stransky
  42. 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
  43. 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.
  44. @jwscott22 The end? “I didn’t think it would end this

    way.” “End? No, the journey doesn’t end here.”
  45. • “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
  46. • “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
  47. • 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