Improving the experience of using a new GraphQL API for the first time is critical to the adoption and engagement of users with your product.
However, getting people to engage with your API for the first time can be tricky. To create a successful experience for the first-time engagement with your API you will have to make it both understandable and useful for people to easily start working with in the context of their own project.
Examples are a great way to create a sandbox for new users to start playing. The problem is, examples can be tricky to use in the user’s project context.
Bit is an open source project that can help users start using your API examples in their own projects,hands-on. Here is how it works.
The API documentation paradox
Code and examples
Understanding your API usually starts with your documentation.
The paradox is that most developers don’t really like writing and reading docs. This makes it hard for both you and your users to create a good experience for a first-time engagement with your API.
What most developers really look for when approaching a new API are examples which they can use in their project and easily play with. The problem is, examples can be hard and tricky to modify in the user’s project.
GraphQL API examples can be tricky
This is why it’s important to make examples a “sandbox” for users to start playing with, change in their own project and and quickly move to actual engagement with our API.
API examples a sandbox with Bit
Trying examples in an external environment doesn’t really apply to your user’s current use case. So, you will have to make sure they can actually play with these examples in their own context right from their project.
Bit is a tool that speeds and simplifies code sharing between projects.
Using Bit, you can isolate and share code right from any repository, install it in other projects with NPM (without having to install Bit) and easily make changes to the code itself from any other repository or project.
This last part can be very helpful when it comes to your GraphQL API, as users can import your API examples as reusbale components into their own code and easily change it to suit their needs. Let’s run through a quick example.
Example: GitHub’s GraphQL API
GitHub’s GraphQl Apollo/create-client API component shared with Bit
Let’s Say that the guys at Github want to make their GraphQL API easier for developers to pick it up and start working with.
The usage spectrum of the API includes the GraphQL queries, the creation of an Apollo client that connects to Github GraphQL API, and maybe even an example of a React component that calls the API.
Let’s use Bit to share all of these components and make changes to the relevant example from another project’s context.
Sharing your GraphQL API
Here is a template project that contains GitHub’s GraphQL API.
We can use Bit to share the API into a collection of components (called Scope) like this one which users can import into their own code.
Sharing our API with Bit
Let’s share GitHub’s API components from the template project.
For this particular example we will have to generate a github token to access GitHub’s API. Then, let’s copy the generated token into ./src/App.jsdirectory instead of the 'YOUR TOEKN HERE' string, and run NPM install.
npm inpm start
Just like Git, you can set up a Bit Scope on any server. To keep things simple, let’s use the free Bit Hub and create a Scope of our own.
Let’s install Bit and initialize it for the project.
# install Bitnpm install bit-bin -g
# init new bit scopecd github-graphql-templatebit init
Now let’s add build and test environments for the code we’ll share. Bit will run them in an isolated environment on the free Hub.
# adding compiler to make sure we can compile our code from any projectbit import bit.envs/compilers/react -c
# adding mocha as tester environment so we can run tests from any projectbit import bit.envs/testers/mocha -t
Next, let’s use Bit to track the code want to share and tag it to lock it’s version and define its dependencies before we share it.
We’ll also run the status command to see that everything is ok.
# tracking all components with Bitbit add src/*/* -t src/{PARENT}/{FILE_NAME}.spec.js
# lock a version for all componentsbit tag --all 1.0.0
# see the tagged components waiting to be exportedbit status
Finally, let’s share the API components to the Scope we created.
# export the components to your own scopebit export [USERNAME.SCOPENAME]
For this tutorial, I already shared this Scope as an example. These components can now be installed using NPM in the user’s project from Bit’s registry even if they are not using Bit and never installed it at all.
Users can also use bit import to bring the component’s actual source code and make changes right from their own project’s environment.
Users can play with your API in their own project
let’s say that a new users is trying to adopt our API.
Once exposed to the Scope we created, they can import any of these examples into their own project and start changing it to suit their real use case.
Here is another example project representing the user’s project. As you can see in the [pakcgae.jso](https://github.com/GiladShoham/github-graphql/blob/master/package.json)n, the user even installed the components using NPM. Let’s clone it to simulate a user’s project.
For the sake of this GitHub API example, let’s also generate the token and copy it into ./src/App.js instead of the 'YOUR TOEKN HERE' string again, and run NPM install.
Changing the examples in the user’s project
Let’s assume the developer trying to adopt our API wants to add the repo’s labels list to our app. Normally, this would be a messy process.
With Bit, they can use bit import to import the queries/ repo-info-issuescomponent’s source code into their own project to change it.
# init Bit for the projectbit init
# bring the component's source code into your projectbit import giladshoham.github-graphql/queries/repo-info-issues
Now they can see the code under components/queries/repo-info-issues and open the index.js file to add the code they need to add a list of 10 labels below nameWithOwner.
labels (last:10) { edges { node { name, color } }}
Once changed, they will also need to change our react component to present the list. Again, with Bit this workflow becomes simple.
The user can import the react component into their project.
# bring the component source code into your projectbit import giladshoham.github-graphql/react/repo-info-issues
The code can now be seen under components/react/repo-info-issues and they can add the label list under the issues ul.
<ul style={{'listStyleType': 'none'}}>{ repository.labels.edges.map( label => (<li style={{'textAlign': 'left', 'color': `#${label.node.color}`}} key={label.node.name}>{label.node.name}</li>) ) }</ul>
Now they can also compile the new code.
bit build
As you can see, Bit installs everything needed for compiling the component so our users don’t even have to install anything for this to work.
Now they can simply run the project.
npm start
As you can see you have the new component rendered correctly.
If they want to share the new version of the components, they can tag and export it to their own Scope and use the updated version from any project.
# see our statusbit status# tag a new version of the modified componentsbit tag -am "added labels list"# export back to bitsrc.iobit export [USERNAME.SCOPENAME]
And that’s it.
Conclusion
Improving the experience of using a new GraphQL API for the first time is critical for increasing the adoption and engagement with your product.
To understand how to make your GraphQL API simpler to adopt, we’ve put ourselves in the shoes of the developer having to adopt our API .
Instead of having to read long docs or work with examples out of their real use case and project’s context, we can use Bit to help them easily pick-up our API and customize it to feet their own use case and project’s environment, leading to a faster and simpler adoption of our API.
Feel free to ask any questions, suggest feedback and give it a try.
I will tweet whenever I publish a new post, promise! ✍