Swagger UI

Swagger UI is an incredibly helpful tool that can be used to learn the ins and outs of an api. The whole thing is an opensource project (swagger.io) that is easy to install. All an api provider needs to do is write a json object specifying what the heck the api does. The json object encapsulates what end points the api has, what inputs it accepts, what outputs it produces and in what format(s), and what errors could be returned etc. Once installed anyone can use the "Try it out!" button to send in requests. It's great fun to see exactly what is returned, whether it's an error or data. You can read all the documentation an api provider supplies but there is no substitute for playing around and actually interacting with the api without having to write your own client. Swagger UI, proverbially, is the stick that lets you poke the api to see how it reacts.

The PEDS (Patent Examination Data System) service providers do have a swagger page for thier api but it's using an older verison of the swagger user interface. The biggest difference I see is that curl commands are generated in the new version. Here I've taken the PEDS swagger object and wrapped it in the newer version of swagger ui.

The PEDS swagger object itself is using swagger version 2.0. There is a 3.0 version out now which is also known as the OpenAPI specification. Here is the same updated swagger user interface using the PEDS swagger object which I converted to swagger 3.0/Open Api (using an opensource project). It looks the same as the swagger 2.0 version but there is a subtle difference. Some opensource projects use the swagger 2.0 object as input and some use the swagger 3.0/OpenAPI object. It's more thoroughly explained in this longer article that makes the case for swagger for patentsview, a similar api.

Note that the swagger pages currently do not work from my domain in most browsers. Chrome throws this error:
/swagger/#/home/showHomePageUsingGET:1 Failed to load https://ped.uspto.gov/api/: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://peds.historicip.com' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.