the experience of using a new API for the first time is critical to the adoption and engagement of users with your product. Improving GraphQL 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 and for people to easily start working with in the context of their own project. understandable useful 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. 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. Bit 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. is a tool that speeds and simplifies code sharing between projects. Bit 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 want to make their GraphQL API easier for developers to pick it up and start working with. Github The usage spectrum of the API includes the GraphQL queries, the creation of an that connects to Github GraphQL API, and maybe even an example of a React component that calls the API. Apollo client Let’s use to share all of these components and make changes to the relevant example from another project’s context. Bit Sharing your GraphQL API Here is that contains GitHub’s GraphQL API. a template project We can use Bit to share the API into a collection of components (called Scope) which users can import into their own code. like this one Sharing our API with Bit Let’s share GitHub’s API components from the . template project For this particular example we will have to to access GitHub’s API. Then, let’s copy the generated token into directory instead of the 'YOUR TOEKN HERE' string, and run NPM install. generate a github token ./src/App.js 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 Bit npm 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 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. shared this Scope Users can also use to bring the component’s actual source code and make changes right from their own project’s environment. bit import 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 representing the user’s project. As you can see in the , the user even installed the components using NPM. Let’s clone it to simulate a user’s project. example project [pakcgae.jso](https://github.com/GiladShoham/github-graphql/blob/master/package.json)n For the sake of this GitHub API example, let’s also the token and copy it into instead of the 'YOUR TOEKN HERE' string again, and run NPM install. generate ./src/App.js 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 to import the component’s source code into their own project to change it. bit import queries/ repo-info-issues # 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 file to add the code they need to add a list of 10 labels below nameWithOwner. index.js 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 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. Bit Feel free to any questions, and . ask suggest feedback give it a try I whenever I publish a new post, promise! ✍ will tweet
