Contents
The nuts and bolts of good API documentation are well known. Describe your endpoints, detail your parameters, provide sample calls, and so on.
With all of these items in place, developers will have a good idea of what they can do with your API. But what should they do to get the results they desire from an API?
If I handed a driver’s ed student the manual to a 2018 Honda-CRV, they could probably figure out how to start the car or turn on the rear defrost. But would they have any idea how to drive the car to grandma’s house? (Aside from, of course, going over the river and through the woods.) If I hand that student a map, or grandma’s home address to punch into their phone, I can be reasonably sure they’ll actually make it there.
That’s why good documentation needs to go beyond what a developer can do with an API to detail what they should do, and how they should do it.
Trimble has been doing this for decades
For more than 30 years, our PC*Miler application has been the transportation industry’s standard for calculating the distance (mileage) between two locations. That way, shippers and carriers are looking at the same distance when it is used to determine the price to transport cargo from one place to another—a process referred to as “rating.”
In recent years, many of our customers have transitioned from our desktop or server-installed versions of PC*Miler to our RESTful web APIs, which use exactly the same routing algorithm. The APIs are fast, always up-to-date, and can be easily integrated into any software. They also provide many different ways that you can generate PC*Miler distances for trucking lanes. A software developer using our APIs may wonder:
- Which API endpoint should I use?
- Which parameters do I need to set (required) and which can I ignore?
- Which settings ensure that the distances match the PC*Miler practical miles I have been generating for decades with PC*Miler on-premise software?
Go with the (work)flow
Good documentation can potentially answer many of a developer’s questions in advance—before they can’t find what they need, get frustrated, and give up. In recent months, we’ve been beefing up our API endpoint documentation with more:
- How-to guides, such as an article about how to generate mileage for rating.
- Workflow documents that include our recommended order for calling endpoints to get the best results.
- Definitions for key concepts and terminology used in APIs.
- Short videos related to specific tasks such as getting the posted speed limit for a particular stretch of road.
- Flow charts showing a typical use case for a set of APIs.
- A developer feedback feature (thumbs up/down buttons on each API documentation screen) where you can let us know whether or not something was helpful and why it wasn’t helpful. (Please do let us know. You won’t hurt our feelings.)
To be sure, you don’t want to discourage developers from seeing what they can do with your APIs. Build, baby, build!
But you also want your documentation to help developers avoid the frustration that comes from not knowing how they should do a specific task, and getting unexpected results. Give your developers the car manual and a map–the result will be a more pleasant trip for everyone.
Share this article:
