If you want to build a simple but attractive looking API documentation site, you can’t really go wrong with an open-source tool like Slate. Despite being created by a teenager developer during a summer internship, it has become an incredibly popular tool with the project being forked more than 15,000 times and with well-known organisations including NASA, Best Buy, Monzo and Skyscanner all using it.
🎬 So what is Slate?
Slate is a Ruby-based tool that generates a great-looking, three-panelled API documentation static site from a set of markdown files. It was built by developer Robert Lord in 2013 when he was an 18-year-old intern at at travel software company Tripit. He convinced his boss at the time to let him open-source the project and the rest is history.
In this example, I’m going to use the generic Swagger Petstore example which I have saved to my Desktop and called petstore.yaml. To convert this to Markdown using swagger-to-slate, open a terminal and run:
swagger-to-slate -i ~/Desktop/petstore.yaml
This saves a file called petstore.md in the same location as the .yaml file. Once you have this, you can get started with Slate.
🔨 Build your site using Vagrant
To build your API documentation site using Vagrant, follow these steps:
Alternatively, if you want to run your Slate site locally, you can also use Bundler. To use this method you must install Ruby version 2.3.1 or newer. To check which version you have installed run: ruby -v
I recently gave a talk at the API the Docs conference in London where I was finally able to share some valuable advice about GraphQL documentation. My talk followed my journey from first being told that GraphQL was self-documenting and didn’t need documentation, to speaking to GraphQL co-creator Lee Byron in my quest for answers and receiving the words of wisdom that I was able to share at the conference.
After initially being told by a developer that GraphQL wouldn’t need documentation, I was pretty sceptical, but as I starting researching I found numerous examples of developers advocating GraphQL’s self-documenting nature with someone even declaring that it didn’t need documentation.
Although the majority of people were fairly positive about the self-descriptive features, one tweet from a developer who was unhappy with the GraphQL documentation he had encountered made me realise I might be onto something.
🤖 What does “self-documenting” mean?
I explored what is meant by self-documenting – something written or structured in such a way that it can be understood without prior knowledge or documentation – and highlighted how the PC Magazine definition came with this caveat about subjectivity:
“It’s very subjective. However, what one programmer thinks is self- documenting may truly be indecipherable to another.”
I investigated the risks of subjectivity, how words like homographs such as “second”, “number” and “subject” can have multiple meanings and might be interpreted differently. I also shared different opinions on self-documenting code, how some people feel it is a myth and an excuse for developers to avoid writing documentation:
Self-documenting code is a myth perpetuated by those who hate to write documentation.
I also referred to a blog post by Write the Docs co-founder Eric Holscher who said self-documenting code was “one of the biggest documentation myths in the software industry”, adding that the self-documenting argument boils down to:
I made something with a specific use.
I gave it a name to represent that specific use.
It doesn’t need documentation now because it’s obvious how it works.
Holscher argued that people who believe in a world of self-documenting code are actually making it more difficult for normal people to use their software.
🔬 How intuitive is GraphQL?
To test some of these self-documenting claims, I stripped out the introductory documentation from the Github GraphiQL explorer and asked six of my colleagues (members of QA, development and documentation) to try and retrieve my name, location and avatar URL with a GraphQL query from just my Github login name.
The results were pretty interesting with pretty much all of them struggling with the syntax and encountering fairly similar parsing errors. The amount of time it took them to formulate a query through trial and error proved to me that GraphQL isn’t actually that intuitive without some form of example query or hand-holding documentation to get you started.
The other common issue I have encountered with some GraphQL APIs was developers either failing to add descriptions or using ‘self-descriptive’ as a description for queries and fields that weren’t particularly descriptive. Some of these relied on assumed knowledge, expecting the end user to have a prior knowledge of the schema and the data it relates to.
After looking at the GraphQL spec, I found this line, which might explain why some developers are not including descriptions: “All GraphQL types, fields, arguments and other definitions which can be described should provide a description unless they are considered self descriptive.”
Whether they realise it or not, the issue is these people are unintentionally making it difficult for people to use their APIs. GraphQL co-creator Lee Byron spoke about the importance of naming at the GraphQL Summit in 2016:
“It’s really important not just to have names that are good but to have names that are self-documenting […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”
🐴 Straight from the horse’s mouth
I thought this was pretty interesting but I still wanted a definitive answer about GraphQL documentation so I emailed Lee Byron, who also happens to be the editor of the GraphQL spec, asking him if he would answer some of my questions. To my surprise he agreed to an interview back in September. We spoke for about half an hour and he told me all about the history of GraphQL, his hopes for its development and we touched upon documentation. When I asked him about the importance of descriptions in GraphQL, he gave the following advice:
“APIs are a design problem, way more than they’re a technical problem and you know this better than anybody else if you’re working on documentation.
If there’s no documentation, it doesn’t matter how good the API is because so much about what makes an API work well is mapping well to your internal mental model for how something works and then helping explain those linkages and the details.
If you do that wrong, it doesn’t matter how good your API is, people aren’t going to be able to use it.”
“GraphQL doesn’t do that for you, it provides some clear space for you to do that.
There’s the types and the fields and introspection, you can add descriptions in places so it wants to help you but if you don’t put in the thought and you end up with a poorly designed API, that’s not necessarily GraphQL’s fault right?”
I asked Lee’s permission to use the video clip of him giving this advice during my talk as I knew it would resonate with other API documentarians and having one of the GraphQL co-creators validate what I’d set out to prove all along was a pretty awesome mic drop moment for me!
✍️ So how do we document GraphQL?
Lee Byron spoke about how GraphQL provides you with “clear space” for the documentation: the types, the fields, the descriptions and introspection. So by using self-descriptive names for the types and fields and by using good descriptions in your GraphQL schema, you make it a much more user-friendly experience for your end user. I have highlighted where descriptions appear in GraphiQL for the Star Wars API (SWAPI):
However, these descriptions will only get you so far because documentation generated dynamically from your schema is never going to be very human.
Former technical writer and developer Carolyn Stransky spoke about this issue and a number of other blockers she encountered while trying to learn GraphQL at the GraphQL Finland conference. These included “an unhealthy reliance on the self-documenting aspects of GraphQL”, unexplained jargon and assumed knowledge. She felt most of these issues could have been easily prevented if more care and consideration had gone into the documentation.
I wanted to see what other technical writers were saying about GraphQL documentation but given the technology is so new, my questions on the Write the Docs Slack channel and other forums went unanswered. However, I did find a couple of good resources.
Andrew Johnston, who works on the GraphQL documentation at Shopify, spoke about the importance of providing on-boarding or “hand-holding” documentation for people who are new to GraphQL and not just assuming your end users will know how to formulate queries and mutations.
Technical writer Chris Ward wrote a blog post about whether GraphQL reduces the need for documentation and concluded that while it “offers a lot of positives on the documentation front”, documentarians should treat it just like any other API. He wrote:
“Documenting API endpoints explains how individual tools work, explaining how to use those tools together is a whole other area of documentation effort. This means there is still a need for documentation efforts in on-boarding, getting started guides, tutorials, and conceptual documentation.”
So my conclusion was GraphQL can be self-documenting but only if you put in the effort to give your fields and your types self-descriptive names, if you add good descriptions and if you provide adequate supporting documentation, especially for people who are new to GraphQL. Ultimately I think technical writers have a pretty important role to play in documenting GraphQL and ensuring the experience works, to repeat Lee Byron’s advice – if your API doesn’t have any documentation then people aren’t going to be able to use it.
I recently interviewed the GraphQL co-creator Lee Byron for Nordic APIs, an international community of API enthusiasts. It was a great opportunity to find out how GraphQL came about, why it was open-sourced and where he sees it developing in the future. We also touched upon documentation and the importance of descriptions in GraphQL, something I’ll share in a future post.
The Adventures of SuperGraph
Ten years ago Lee Byron was a graphics engineer designing interactive news graphics at the New York Times when a friend approached him to join a small social media startup based in San Francisco, California. The company was Facebook, which had only just surpassed MySpace as the world’s most visited social media website at the time, and four years later Byron would find himself managing the team working on the Facebook native iOS app when the first seeds were planted for what would later evolve into GraphQL.
“Right around then our mobile apps were built with HTML, they had native wrappers around them and they had suffered from real performance problems,” he said. “We made a bet on that technology thinking that Apple and Google would maintain really high quality web browsers and they didn’t so that didn’t really work out very well and we decided we needed to build a native app.”
“We started this little skunkworks project where two engineers from my team and two engineers who were relatively new to the company started building out what would become the native iOS app for News Feed.”
The team produced a high quality, working prototype but Byron spotted that News Feed stories were missing because they had used a three-year-old, unsupported platform partner API and he realised they would need to build a new one.
“That kind of sent things to crisis,” he said. “They thought they were almost done and it turned out they had a ton of stuff left to do so I started focussing in on those problems and I was like “Okay, I need to build a News Feed API somehow. Who are the people I need to talk to? How does that need to get done?” A big problem is that the News Feed is incredibly complicated and typical API technology probably wouldn’t do quite the right job so I started sketching out what a good API might look like. It definitely wasn’t what GraphQL is now but it was sort of like really beginning inklings in that direction.”
“Meanwhile another one of the GraphQL co-creators Nick Schrock had just spent the last couple of years working on a bunch of data infrastructure on our server side and had spent a little bit of time exposing some of that over APIs, not GraphQL but a different kind of API, and had an idea about how this could be made much, much more simple so I credit Nick Schrock with the first prototype that really resembled GraphQL. He called it SuperGraph.”
A screenshot of an early GraphQL prototype that Nick Schrock called SuperGraph.
A member of Byron’s team introduced him to Schrock and Dan Schafer, hailed as the best News Feed engineer at Facebook at the time, and the trio started work an initial version of GraphQL. “The three of us got to work trying to figure out how to build a better News Feed API and we just got super far down the rabbit hole,” Byron said. “I think just a month or two of iterative improvements on what started as a prototype enfolding all of our ideas ended up being the first version of GraphQL.”
The launch of the native iOS app, helped by the introduction of GraphQL, was a success and the excitement around GraphQL and its capabilities made other Facebook teams interested in using it. As a result, Byron and the early GraphQL team would go on to develop a whole ecosystem around GraphQL; how it integrated with the iOS and Android apps, how it integrated into the server and GraphiQL, the in-browser IDE.
“We were excited about it,” Byron said. “I mean sharing things with the community is always good but it would be a lot of work and we weren’t totally sure people outside of Facebook would even care or find value in it. We thought maybe this was something that only solves a Facebook problem and wasn’t a generic solution but the Relay team had us excited so we followed that path and I’m super happy that we did. GraphQL now has a really big community outside of Facebook.”
The release and adoption of GraphQL
The adoption of GraphQL took far less time than the team initially predicted. Speaking at the first ever GraphQL Summit in October 2016, Byron said he hoped GraphQL would be picked up by big companies within four years and reach ubiquity within five years. Byron laughed when he reflected on the accuracy of those predictions.
“I think I overestimated how long it would take for large companies to adopt it and underestimated ubiquity,” he said. “It’s probably because ubiquity is kind of vague but certainly I still talk to tons of people who work in the API space and at best they say “Oh GraphQL, I think I’ve heard of that before but I don’t really know what it is”. It’s certainly better this year than it was last year and better than the year before that.”
He added: “I remember going to an APIDays conference shortly after the first GraphQL Summit and literally there were zero talks on GraphQL. After the next one, there was a whole track talking about GraphQL. The one after that GraphQL was featured in one of the key notes and there wasn’t a specific track but GraphQL was scattered around. So it’s definitely picking up steam. I think there’s visible progress towards a ubiquity, if we want to talk about ubiquity as knowledge. People are aware of the technology and what it does and why they should use it or not.”
One of the biggest surprises for Byron was seeing Github become one of the early adopters of the technology, particularly as he considers them an API leader.
“I was really surprised to see that within a year of GraphQL being open-sourced, Github decided that their public API would be GraphQL,” he said. “That was particularly significant because they kind of helped to popularise REST. You know REST has been around for a while but it wasn’t really the dominant, popular way to build APIs until Github decided to build their API and they used REST and they made a big deal about it and wrote a bunch of blog posts and everybody paid attention.”
He added: “I thought “Wow, this API is really well built, it must be because of REST” and it was to a large degree but it’s also because the people at Github are really smart and they built a really great API. It’s really exciting to me that I consider Github to be sort of an API leader and they jumped on that first and they’re not the only ones any more.”
GraphQL and REST APIs can co-exist
Although GraphQL has been lauded as the natural successor to REST technology, Byron is modest about its capabilities and believes the two can co-exist.
“There are plenty of things that REST does well or that does better than GraphQL and vice versa,” he said. “I’m a big believer in the more tools that we have, the more choices that we have to solve problems. I’m certainly not one of those people who that think I’ve invented the silver bullet here and everything should be GraphQL and there’s no room for anything else. I think that would be a little unwise. I think REST is an amazing technology so I would be really sad to see it disappear.”
“I’m certainly not one of those people who that think I’ve invented the silver bullet here and everything should be GraphQL and there’s no room for anything else. I think that would be a little unwise. I think REST is an amazing technology so I would be really sad to see it disappear.”
“I do think that as GraphQL continues to expand in scope we’ll see a much healthier balance between the two. My expectation was that public APIs would remain REST because that was simpler and more familiar where internal APIs, so to build your company’s own product, would use GraphQL because while it brought more complexity, it also brought some more expressiveness and capability.”
As GraphQL continues to grow, one of the things Byron is excited to see is more public APIs adopting the technology, like companies have done with REST.
“I think the space of public APIs or partner APIs is particularly interesting because I think the vast majority of GraphQL adoption so far has been for a company’s own internal projects. For example, Walmart use GraphQL but they use it for the Walmart app and I think it would be really interesting if GraphQL starts to be used for these public and partner APIs so that we have companies that are working with each other and then it’s not just about the API design and the mental model for within that company but between companies.”
“I think that could be really interesting because it could help start to build one conceptual graph of all information. I don’t think GraphQL is going to be the technology that gets us there but that’s one of the big dreams of the internet is that we could have the one data internet but we need to start having some serious conversations along that path if we ever want to get there. I think GraphQL could be a really useful stepping stone on that path.”
Hopes for the future of GraphQL
Despite being happy with its growing popularity and some the open-source development going on around it, Byron hopes to see more growth in GraphQL tools and integrations.
“It’s kind of sad that there’s the Apollo Client for iOS and Android and then that’s kind of it,” he said. “There needs to be many competing pieces there and that’s true for any sort of technology that’s reached ubiquity has at least two if not closer to a dozen different options for how you would go about implementing that. If you wanted to build a web server, there’s like hundreds of ways to build a web server in dozens if not hundreds of languages and that’s kind of where I want to get to with GraphQL as well.”
Byron left Facebook after a decade of service to become head of web engineering at fintech startup Robinhood earlier this year, citing the desire to work at a smaller company and its refreshing vision as some of his reasons for leaving.
“Robinhood’s roughly the same size today that Facebook was when I joined it and I really missed that and I realised that some of the best work that I did at Facebook was when there were a little smaller. Not that Facebook’s not a great place to work now, it’s just I really appreciated having the smaller work environment and was happy to have that back.”
“I’m also just kind of interested in finance in general so it’s a new space for me to learn which has been pretty fun and then they’ve got a bunch of really interesting technical challenges and people challenges. That’s my bread and butter. I really love technical problems and people problems, then the product problems I’m interested in but it’s new to me so there’s room to learn.”
On top that, he is still the editor of the GraphQL spec and runs the working group meetings to ensure that GraphQL continues to improve while also maintaining stability.
“One my of goals for GraphQL is that it is stable because Amazon and Twitter and Pinterest and Airbnb and Facebook and Walmart and so many other companies have bet their future on GraphQL,” he said. “If GraphQL changes so rapidly that every year there’s like maintenance work to have to go in and improve all of those pieces of infrastructure, if I was an engineering director at those companies I’d feel shaken and I’d question the choice to use that technology. At the same time I want to make sure that there’s room for it to grow and improve and those improvements don’t have to come from me. I don’t think that I’m the smartest person in the room. I want to make sure that experiences of people from lots of different companies and environments can help influence that direction.”
He added: “GraphQL is still new. I’m really impressed with how much has been built by the open-source community and how much adoption has happened within the open-source community, especially the large companies. I mean, there’s a ton of large companies that are using GraphQL and that’s only three years out from open-sourcing, I think that’s pretty incredible but there’s always room to grow.”
If you Google for ‘API trends’ or ‘the future of APIs’ , one technology that crops up a lot is GraphQL. Developers rave about it being a more powerful and flexible alternative to REST. Not only that but if you’re a technical writer like me, claims that it is self-documenting are particularly interesting. So what is GraphQL and is it really as self-documenting as people say?
What is GraphQL?
GraphQL is an open source data query and manipulation language that was developed internally by Facebook for their mobile applications before being released publicly in 2015. Since then it has grown in popularity with some people claiming it might replace REST APIs in the future.
Like REST APIs, both operate over HTTP with requests being sent to retrieve or manipulate data. The key difference is with REST you might need to send requests to multiple endpoints to retrieve a particular set of data, with GraphQL there is only one endpoint so with a single request you can retrieve an object and all of its related objects.
For example, with this GraphQL schema and server wrapping the SWAPI (Star Wars API), you can retrieve multiple pieces of data using just one endpoint. In this case, finding out the species and home planet of Luke Skywalker by adding more fields to the endpoint:
“The self-descriptive nature of GraphQL”
There seems to be plenty of love for GraphQL on Twitter with developers praising its speed, flexibility and introspective nature. The other key attribute that crops up a lot is “self-documenting” or “self-descriptive”:
The self-descriptive nature of GraphQL and the visual, auto-completing, browser-based query builder "GraphiQL" is pure genius.
One developer even went as far to say that GraphQL doesn’t require documentation at all. However, after playing around with GraphQL and experimenting with some public GraphQL examples out there, I’m not so sure I agree.
The key thing about GraphQL from a documentation perspective is the importance of naming. Lee Byron, one of developers behind GraphQL, spoke about this in his talk “Lessons from Four Years of GraphQL” at the GraphQL Summit in November 2016: “Naming things is super important in GraphQL APIs,” he said. “An important question to ask when designing APIs is ‘Would a new engineer understand this?'[… ] And that means no code names or server-side lingo.”
He continued: “Imagine that most of the engineers who are going to be using your API might not find it so easy to go and find out how that field maps to some underlying system. It’s really important not just to have names that are good but to have names that are self-documenting. Naming things that adhere closely to what those things actually do is really important to make this experience actually work.”
“An important question to ask when designing APIs is ‘Would a new engineer understand this?’ […] Naming things that adhere closely to what those things actually do is really important to make this experience actually work.” – Lee Byron
Despite Byron’s warnings, fields with poor or no descriptions were a common issue in the different GraphQL APIs I looked at. In the example below, taken from the GraphiQL documentation explorer, I had no idea what the ‘section’ query field did or what data it sent back because it had no description:
Apart from the documentation explorer, another way to see what query and mutation fields are available is the auto-populating feature in GraphiQL. Hovering over the field or type reveals a description but this can be as useless as the description in the documentation explorer if all it says is ‘Self descriptive’, as this Twitter user found out:
I agree that GraphQL is self-descriptive and if you’re familiar with the query language and the schema, its introspective nature means it is easy to refer to the description of a field or type to find out what it does. One of the other advantages of GraphQL is the API documentation is easy to keep accurate and up-to-date as the descriptions are pulled directly from the code. In version 0.7 or above of GraphQL, this is as simple as adding a comments directly above the type or field in the code:
However, GraphQL is only “self-documenting” if the developer or a technical writer has given the fields adequately intuitive or self-descriptive names or has added decent descriptions for them in the schema code. If the names are obscure or the descriptions aren’t great then your GraphQL API is as useful as a chocolate teapot and there are already a few chocolate teapots out there from what I’ve seen. So I guess the good news for technical writers is that we still have a role to play in helping to document GraphQL, it isn’t a magical solution that renders us unnecessary just yet!