Why do I need to care?
- Developers who want to use your API want to have uptodate documentation. That is taken for granted. No exceptions.
- If you want to help new developers to onboard and get familiar with your API faster you need to supply more.
- Developers don’t want to read about things too much.
- They want to fiddle and play with things before taking it into use.
- Developers want to see your API in action!
- The faster developer is convinced of the value of your API - the sooner they become (perhaps indirectly) paying customers.
If and when they are convinced about your product they will read more. Then they explore the API more and possibly even read your precious API documentation to find an answer. Even in those cases documentation works as a backbone or support (not the most important part of your API product) while learning to use it. How? Let’s explore this a bit more.
Simple try it out examples
One of the most simple playgrounds is runkit.com which you can embed to any website easily. It offers execution of simple (or complex) code example of how to call your API from node. There’s no login in runkit mode, thus you can’t use developers personal access tokens or alike in the examples. That limits the runkit a lot and that is also why I see that tool more like a marketing stunt than anything else. It has value, but not in every day life for the developer.
This is what for example Stripe uses in their frontpage
Machine-readable spec files are part of the documentation of any great API as it was written in previous post. OpenAPI specification (formerly known as Swagger) is one of the most commonly used spec format with REST APIs. It is enforced by plethora of API development companies and developed under the wings of Linux Foundation. Tooling around OpenAPI spec has exploded with the popularity. One of the tools in API viewer which renders the specification file in “human format”. If used right, it can act as testing and learning environment both internally and by 3rd party developers. Swagger Editor was probably the first one to offer instant interaction with the APIs.
After that a plethora of solutions emerged and you can find a lot of them by googling around. With the consoles integrated as part of you Developer Portal, you can use personal tokens since your customers can login to it. Offering a playground for developers to test your API in for example your Developer Portal is an option. I personally don’t like it so much. It’s kind of limited since I can’t modify the calls freely and I have no way to store API calls I’ve used for later use. Thus I’ve become a fan of API client or development environments. They are more versatile and easier to use both internally and externally.
API development and testing environments
Postman is one of the most popular tool to dissect RESTful APIs made by others or test ones you have made yourself. Postman and alike tools can be used to get familar with APIs without writing any code. These tools are prettier GUI alternatives for testing APIs with cURL among other things. The point is that the same tool can be utilized by internal developers (building the APIs) and 3rd party developers consuming the APIs. These environments give the developer a lot more freedoms than API consoles.
Ready - set - Go!
One familar format to enable easy setup for 3rd party developers, is to export collections for the selected tool. This is what Postman offers - collection with environment configurations. By importing the ready made collection of API calls the 3rd party can start exploring the API with own tools and own environment (desktop). As for GUI alternative is to offer browser based API console in which 3rd party developer can make requests to the APIs. Yet Postman and alike solutions are very versatile and often easier to use. At the same time a lot more can go wrong in here and developer does not get any success. Furthermore you need to upddate the collections too.
Which one to choose?
I asked our developers about why they chose Insomnia over Postman and reason is that again Insomnia fits better in the teams workflow and is considered more agile in development. The overall image of Postman inside the team was not that good:
- “They Insomnia tend to address the bugs and feature requests in GitHub pretty fast”.
- “whereas Postman refuses to provide a good fix for a critical issue causing issues to lots of people and has been reported years ago”
- “compared to my last experience with Postman, Insomnia is easier for both new users and experienced users, as well as just having more useful features, and most critically - less bugs.”
- “I initially switched to it simply because the
hostsbug made Postman unusable”
The above reasons among others has turned our developers to use Insomnia instead of market leader Postman. Given the above situation my options as Developer eXperience lead are:
- Force the team to use Postman because that is most often expected
- Create / get a tool to convert Insomnia export to Postman collections
- Use Insomnia and offer needed configuration for that in public for 3rd party developers.
Option 1 is out of the question in short term. I will not force developers to use other tools than what they see fit. They have selected the tools for a reason and messing with that would cause more new problems than solve any existing ones. Second option is more likely to exist in some form (did not check yet) as a tool or service, but conversions contain always a risk to break something. Thus I did select to go against the mainstream even if I know that some of the API consumers want to see Postman collections. We will provide Insomnia settings and package to fiddle with our exposed APIs. Of course we provide detailed guide how to work with the Insomnia in minutes and start learning the opportunities and options of our APIs.
In my opinion top API documentation examples combine 3-column documentation formatting and runnable code examples into one compact package. That is what we are after too at Platform of Trust. That still requires user to login to API Docs so that we can replace the TOKEN fields with real tokens. And then of course the “copy” button next to the code examples.
Offering API console instead of collections for Postman might be the thing. You need to know what your primary customers (developers) want. In the end both approaches offer means to test your API.
Some more to read from 100 Days DX
- #85 - Great Developer eXperience requires fluent internal workflow
- #84 - Theory of Economics of Developer eXperience
- #83 - The Space of API Design Decisions is missing
- #82 - Purpose of API Evaluation Framework
- #81 - Should We Move to Stack Overflow?
- #80 - Four data driven ideas for improving API documentation
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!