Usps web tools api12/17/2023 ![]() At times, it is hard to tell how children objects are organized and if they are returned as arrays. USPS documentation does not provide examples of the variety of responses you might encounter based on different conditions. The biggest challenge in this project was the size and complexity of response objects. To create an OpenAPI specification that is valid (with all endpoints) and generates accurate documentation, we used this hacky work around of defining a parameter named API AND appending it to the path (thereby making each path unique). This presents a problem since all endpoints use the same path /ShippingAPI.dll and define their function via the API query param. Redoc inserts a new section without an associated endpoint-voila! Problem #2įor an OpenAPI 3.0 specification to be valid each path must be unique and methods (GET, PUT, POST, DELETE, etc) can only be used once per path. To accomplish this we added a description of authentication using tags in OpenAPI and set the x-traitTag to true. We still wanted to explain how USPS Web Tools authentication works. This removes an automatically inserted link to authentication details that accompanies each endpoint. Omit the security scheme from our specification and use the Redoc option noAutoAuth=true. ![]() Instead, a USERID attribute equal to the developers Web Tools username on the parent node of the XML query param acts as an API key. USPS APIs don't use any of these authentication types. Available types include http for basic and bearer, apiKey where a key is passed via a header, query param or cookie, oAuth 2 and OpenID connect. ![]() OpenAPI 3.0 defines the authentication approach in the security scheme component. Our first challenge was the non-standard authentication used in the USPS APIs. We achieved our goal of a valid specification, but compromises were necessary to accommodate the U.S. APIs do not always follow established standards and quirks may have crept in that donât fit a specification. Taking existing API docs and creating a OpenAPI specification from them might sound straight forward, but it can be tricky. Reverse engineering an OpenAPI specification Letâs look at the challenges we faced improving the developer experience. Many companies offer an interactive API explorer as part of their documentation, we thought a good solution was a USPS Web Tools public workspace with Postman. Finally, we created a video tutorial so you can try out these tools. We crafted a USPS Web Tools OpenAPI 3.0 specification from the PDF docs, then used the spec to generate modern USPS Web Tools API documentation with Redoc and host them on Netlify. API documentation often ranks number one for how developers evaluate a technology and the USPS Web Tools APIs reference docs are only available as PDFs, so we decided to start there. Now, we canât change the APIs themselves, but perhaps an open-source project that leverages new tools could make a difference. Unfortunately, many of these endpoints were developed over a decade ago and during the intervening years developers have come to expect increasingly better and better developer experiences.Īs we looked at the USPS Web Tools site, we started thinking of ways to improve the experience. Their current API set includes address verification, rate calculators, shipping labels, package pickup, domestic mail service, tracking & confirmation, and even an API to retrieve Hold for Pickup facility information. Postal Service opens up their data and makes it easy to access with a free USPS Web Tools® account. ![]() ![]() Lob also utilizes the USPS tracking data in our webhooks so customers can observe the journey of each mail piece. The mail that flows through Lob to our print partner network reaches its final destination with help from the U.S Postal Service. At Lob we help developers automate sending letters, checks, and postcards, and improve address quality through RESTful APIs. ![]()
0 Comments
Leave a Reply.AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |