API documentation entails all of the technical content published detailing how to effectively use and integrate our APIs. Crucially, documentation is not limited to technical documentation about how to integrate the APIs, but it also includes guides detailing how to use the APIs effectively.
If you're in the ecommerce space, you're well aware of how valuable yet costly development time is. Developers are often juggling multiple different projects with varying deadlines so it's critical they spend their time efficiently. Confusing and ineffective documentation for third-party APIs will only lead to frustration and missed deadlines.
Effective documentation means that developers spend minimal time getting APIs up and running and it mitigates the likelihood of developers having to double back their efforts after building out the first integration. Effective documentation also allows developers to quickly diagnose error responses from APIs and to understand how to best proceed. Not only does effective documentation detail how to integrate into APIs but it also provides guides on how to best use the suite of tools together. In short, effective API documentation is the most important aspect for developers to spend their time efficiently using our tools.
EasyPost documentation is written and maintained by developers purposefully. We often hear how much developers love our API documentation and how simple implementations are. In the next section, we talk about all of the innovative things EasyPost does to deliver the most effective API documentation in the industry.
EasyPost evaluates the effectiveness of our documentation by the percentage of feature coverage in our client libraries across our seven supported languages (Ruby, Python, PHP, Java, Node.js, C#, Go). We regularly survey our customers to capture their time to implement and to understand how documentation can improve.
The below metrics detail our current client library coverage across all supported languages. We look at client library coverage broken out by "basics" features supported and all features supported. We define our basic features as the following: addresses, parcels, insurances, shipments, and trackers. All features include the basics features and all remaining features described in our API documentation. We break out the basics features' coverage metrics because we see the most volume on these features. We have dedicated teams actively working to improve our coverage to 100% across all features.
In the next section, we outline some of the key innovative things we are doing to deliver the most effective documentation in the industry.
The below list of items details some of the key innovative methods we employ to provide effective documentation. However, there are many common industry best practices we also employ not described below.
1. Official client library support across Node.js, PHP, Python, Ruby, Java, C#, Go
EasyPost simplifies integrations and reduces implementation time by supporting several client libraries including Node.js, PHP, Python, Ruby, Java, C#, and Go languages. Client libraries drastically reduce implementation time from a multi-day scope to just minutes by providing written code that developers no longer need to draft themselves from scratch.
We commit to reviewing and updating our client libraries monthly with dedicated full-time engineering resources. Further, we differentiate our documentation by supporting seven key languages where most of our competitors will support 2-3 (if any at all). We also have an unofficial community client library with contributions from our community of EasyPost developers for all of our customers to benefit from.
2. Public Postman workspace
Postman is a software tool with over 10 million users that helps people in the SaaS community understand and interface with API endpoints. We provide a public Postman workspace to help developers get acquainted with our APIs more quickly and to ensure learnings are shared across our entire customer base. Using the Postman workspace and client libraries together, developers spend minimal time learning and implementing our APIs.
3. Code snippets
EasyPosts provides code snippets on every feature described in the documentation to maximize the usefulness of the documentation. The code snippets within the documentation can be toggled to the preferred language. This helps developers to quickly understand how features described in the documentation can be integrated and allows them to test features quickly.
4. Clear error documentation
EasyPost documents an exhaustive list of error codes with clear intuitive descriptions so every developer can immediately diagnose errors. Additionally, we document examples of how to catch errors across all supported languages in our client libraries (Node.js, PHP, Python, Ruby, Java, C#, Go). Client libraries can be used to build quick implementations to catch common errors thrown such as receiving an invalid address format when creating a verified address. Our support team contact information is published throughout the error documentation as well.
5. Consistency and accessibility
EasyPost intuitively begins documentation with authentication, the starting place for accessing our APIs. We then describe the universal attributes for the objects developers encounter when accessing the APIs. We bold all objects throughout the documentation to annotate custom EasyPost items.
Additionally, API documentation is provided on one single webpage for all APIs and services so developers can quickly navigate through the page to find what they need. EasyPost ensures all features and services are categorized under one of the core services (i.e. shipments, address verification, trackers, etc.) so documentation is easier to navigate.
6. Supporting guides
Guides are critical for connecting the dots across documentation, so we have published supporting guides around all core functionality (creating a shipment, purchasing label, tracking, address verification, webhooks) where we see the most traffic in our API documentation.
We provide detailed carrier guides for the major 4 domestic carriers (USPS, UPS, FedEx, DHL) as well as some of the non-domestic major carriers (Royal Mail, CanadaPost, CanPar). These carrier guides detail how to integrate and what features are unique to that carrier. We also include guides for some of our advanced features such as using batches.
7. Updating and versioning best practices
EasyPost ensures updates to documentation are made clear and previous versions of the client library are maintained and easy to access. If features are deprecated or updated, we preserve the name of the feature in our documentation, and detail the update made clearly. We follow industry standards for each supported language when serving new versions of documentation (i.e. using Node Package Manager for Node.js). When we release a new version of a client library, users are not forced to immediately update and can download previous versions quickly with documented commands. Following these practices ensures that developers can easily stay up to date with our upgrades, but do so on their own time.
We know many components comprise an enterprise-grade API beyond just scalability. This guide is one part of a series of guides that describe all of the different aspects of our enterprise shipping APIs. Click below to learn more!