EasyPost’s API Documentation Guide
by EasyPost
Successful implementations and happy developers depend on clear, effective documentation. That’s why our EasyPost API docs are written by developers for developers. This guide explores what sets EasyPost’s documentation apart and the innovative practices we use to deliver one of the most developer-friendly experiences in the industry.
What is API documentation and why is it so important?
API documentation entails all of the technical content we’ve published detailing how to effectively use and integrate our APIs. Crucially, documentation covers both the technical documentation about how to integrate the APIs and the 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 often juggle 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 allows developers to spend more time using our tools and less time figuring them out.
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.
How do we measure the effectiveness of our API documentation?
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 basic features supported and all features supported. We define our basic features as the following: addresses, parcels, insurances, shipments, and trackers. All features including the basic features and all remaining features are described in our API documentation. We break out the basic 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 will outline some of the key innovative things we are doing to deliver the most effective documentation in the industry.
How do we provide effective documentation?
We employ several key innovative methods to provide effective documentation. In addition, we follow many common industry best practices 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 two to three (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
EasyPost 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 that 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 that updates to documentation are made clear and that 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 clearly detail the update made.
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.
Related Guides
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!
Ready to talk with a shipping expert?
Effective API documentation is critical to our customers’ success, and we’re committed to going beyond "good enough." Expect to see our success metrics continually improving as we explore new, innovative ways to support developers at every step.