It is very important to have a proper documentation of your API because The Documentation is the third user interface for APIs.
To start your API documentation, which help us to focus on the questions that your clients will ask to you. From the first time they encounter your API, to their initial ‘hello world app’ and beyond, the questions they will be asking are wide ranging. If you are able to answer these questions you will be able to help your client to understand what problems your API solves, engage with their first integration, and address their concerns as they consider formally adopting your API.
1: Do you have an API?
API-based products are still a relatively new concept for different industries, be explicit in your mentioning that you provide an API on your corporate website and in all marketing materials.IT is always better to help visitors to learn a little more about your product offerings and API at the same time.
2: What can I do (and not do) with your API?
Once your audience begins to explore your API, they need to know what it does (and doesn’t do). Start with the problems your API aims to solve first, and then move on to the features of your API that solve those problems.
By focusing on the problems and resulting solutions, you focus on the need rather than specific API endpoints. This is often accomplished through: getting started guides, integration/solution guides, and reference applications — all scattered with lots of easy-to-read code examples that can be used as a launching point once development begins.
3: Does your API fit my company’s needs?
By offering use cases, case studies, and example applications, your product is easily aligned with the kinds of customer segments that you want to attract (and as a result you focus less on other segments). These documentation assets also builds trust as customers begin to see similar companies as themselves, causing them to picture themselves solving similar problems.
4: How much does it cost?
Ultimately, price is going to become a factor. Be up-front with your pricing. Don’t hide your pricing behind a “Call us” link.
At a minimum, provide enough pricing information to help them understand your pricing model (e.g. subscription, per transaction), subscription tiers (e.g. free, solo, team, enterprise), and what kind of support is available for each tier (e.g. forums, email, 48 hour phone, 24 hour phone, 4 hour phone). Being up-front with your pricing helps those conducting research and prevents them from removing you from their short list due to your more closed pricing approach.
5: How does your API view my world?
Different APIs approach problems from different angles. Not all APIs are relevant or appropriate for all issues, and so documenting your API concepts, resources, data structures and file types will allow developers to determine whether your work fits in their world.
6: How do you secure your API?
Security of your API is important, particularly with the API security stories recently in the news. Too often, however, security is an afterthought when building APIs.
Your documentation should provide details on how your API handles authentication, authorization, and data security (both security in motion and security at rest). This will reinforce your product’s dedication to a professional, production quality service that will stand out against competitors.
7: Do you offer helper libraries/SDKs?
Not all developers want to code the HTTP client from scratch. This is particularly the case for developers that are new to web API integration, or for those that prefer to use their IDE and code completion to get their job done faster. If you offer SDKs, reference them in your documentation as well as in code examples.
8: What API endpoints and event integrations does your API offer?
You will notice that we are nearing the end of our questions and only now getting to API reference documentation. Reference documentation is only one part of a complete API documentation strategy, even though it is an important one.
9: Why am I getting this error code or unexpected response?
Once developers start to work with your API, they will likely encounter unexpected errors. Offer support docs with FAQs, troubleshooting guides, and developer support to help them overcome these issues and be successful. Documentation that consists of getting started guides only should be considered incomplete.
10: What do I do if I’m not a programmer?
Not all visitors will be developers to your site. For those that aren’t, show them ways to use your APIs via tools or an integration partners page. If you can give demonstration of your API through a simple web or mobile app, that will add spark their imagination and get them to take action.
Top comments (0)