feat: shorthand for readme-hosted APIs (@subdomain#uuid)

[gkoberger]

🧰 What's being changed?

This updates the main URL entrypoint for pulling down OpenAPI definitions to support our upcoming API Registry shorthand accessors like:

• @petstore/v1.0#n6kvf10vakpemvplx
• @petstore#n6kvf10vakpemvplx

These accessors are remapped on-the-fly within our caching layer to pull down the API definition from our API registry API endpoint at https://dash.readme.io/api/v1/api-registry/:uuid`, where :uuid is the last part of the accessor: n6kvf10vakpemvplx

👨‍🔧 Usage

Before

const sdk = require('api')('https://docs.readme.com/openapi/5f7ceacf43621b0311080a58');
sdk.auth('auth_here');

sdk.getAPISpecification({perPage: '10', page: '1', 'x-readme-version': '2.0'})
  .then(res => res.json())
  .then(res => {
    console.log(res);
  });

After

const sdk = require('api')('@developers#7r4794hfjfi');
sdk.auth('auth_here');

sdk.getAPISpecification({perPage: '10', page: '1', 'x-readme-version': '2.0'})
  .then(res => res.json())
  .then(res => {
    console.log(res);
  });

[gkoberger]

Okay, I've thought about this a bit more, and there's some issues:

Problems

1. If someone changes their subdomain or churns, this will break anyone using their API
2. Not everyone has a good subdomain

Solution

Since OAS IDs are unique, what if we changed the syntax to always be @readme/123abc123abc, and had that resolve to something like https://specs.readme.io/123abc123abc?

Then, we should just never delete OAS specs ever (like, say, npm) so that we don't break people using APIs, even if the company churns or deletes it.

[gkoberger]

I made it a bit more flexible.

I think we should still use @subdomain as the prefix (not necessarily @readme), so that people are clear what's happening when reading the code (Even though we don't use it for anything)

• ⛔️ This is bad because it isn't whitelabeled: api('@readme/5f87734f218d9bf534524e12')
• ⛔️ This is bad because it's not clear what API it's calling: api('5f87734f218d9bf534524e12')
• ✅ I like how this indicates what API it is! api('@lyft/5f87734f218d9bf534524e12')

Note: The endpoint I mention here isn't real! We'd need to create it. Which makes sense, it's kinda weird it doesn't exist already... Or, we can create a separate endpoint that doesn't use our official API?

[erunion]

Talked offline over the weekend and to accomidate enterprise users, we're going to do a few things:

• During snippet generation we're going to look at the domain and use the base of it for the name portion of the @name/id key.
• If the snippet is being run on a *.readme.io domain, we'll use the subdomain.
• If a customer wants to override the @name complete, we'll create a new x-api-project-name OAS extension that can be added into the API definition.

[gkoberger]

And just to clarify a bit for people reading this... the @whatever itself doesn't matter at all! It's just to make the code snippets clearer!

[erunion]

Been a while since there's been an update on this:

1. The new format for the shorthand is @petstore/v1.0#uuid
2. Requests are going to hit a /v1/api-registry/:uuid endpoint on the ReadMe API.
3. We aren't going to add a custom OAS extension for overriding the @petstore name for now.

[erunion]

@Dashron @domharrington @gkoberger This is all ready for review now and up-to-date with the new API Registry endpoint that'll be live next week.