Code-generating NGPVAN API client.

[alxmrs]

NGPVAN appears to use the Swaggar / OpenAPI spec to generate their documentation with readme.com. This means that if we could find access to the swaggar.json (e.g. the spec for their docs), we could use code generation tools (1, 2, 3) to automatically produce a Python API client for NGPVAN.

Detailed Description

I spent some time seeing if there was some way that I could scrape the NGPVAN API from the website. Using Chome Devtools, I was able to find snippets of JSON of the API spec per each endpoint. Due to a cross-site-origin header, I was unable to script out a way to get the specs en mass.

However, I noticed a strange pattern in their readme generated docs – namely this code:

const sdk = require('api')('@ngpvan/v1.0#5r6sg7sl74xoc30');

Looking further, I found that api is an npm library that makes use of the swagger api spec for the node SDK. By reverse engineering this library, I could probably get access to the swagger spec that NGPVAN has not made available.

Indeed, this line of code reveals what that junk is at the end of the string above:

https://github.com/readmeio/api/blob/a9c6ce28b3bcb6981e2135180c19f39ef6f025af/packages/api/src/fetcher.ts#L24

Thus, the URL for the swagger spec for NGPVAN is: https://dash.readme.com/api/v1/api-registry/5r6sg7sl74xoc30

Context

Code-generating an Python API Client has several benefits:

• Saves on manually having to write a connector for every endpoint of the NGPVAN API
• If the API changes, all we have to do is re-run the code generation system to get the latest API client.

It's worth saying, code-generation comes with tradeoffs, too:

• Short of writing your own tool, using a generic code-generator often leaves you with opinions / cruft that you don't need or want.
• Extra work would be required to bridge between Parson's tables and the code-generated output. It's likely that extra coding would be needed to adapt between the two paradigms, meaning more work beyond "just regeneration".

Possible Implementation

1. https://swagger.io/tools/swagger-codegen/
2. https://github.com/swagger-api/swagger-codegen
3. https://github.com/OpenAPITools/openapi-generator

Priority

low priority -- this is more of an R&D project :)

[alxmrs]

This project will require more work than I anticipated; here's why:

• NGPVAN uses OpenAPI spec v3.1
• All the available code gen tools (listed above) currently don't support 3.1 (despite their docs which say they support 3.x)
• Currently, this spec support is being built, see Support OAS 3.1 ? swagger-api/swagger-parser#1535 (comment)

The current pathway forward here seems to be to experiment with not-yet-release code generators (or, maybe writing my own), or to wait until there's official 3.1 support.

[alxmrs]

Here's a prototype client API that I've made with this generator:

https://github.com/alxmrs/ngpvan-api-client

YMMV.