0.17 Feedback

[philsturgeon]

I'm working on a writeup of this excellent specification for @bump-sh and my fresh eyes are spotting some things which are not explained. To save spamming I'll just make a big ol' list over here as I go.

1. Define type values

I am seeing this list of Index, Collection, or Blueprint, but I don't really know what any of that means and its not explained elsewhere, and the only examples are type: index.

• type [Optional]: Type of collection (Index [of a single API], Collection [of multiple APIs], Blueprint [of a new API]).

2. Related to 1, two mentions of Blueprint

The only time Blueprint is mentioned is in the list Properties Elements along with OpenAPI, AsyncAPI, RAML, Blueprint, WADL, WSDL etc, suggesting this is referring to the old API Blueprint description format, meaning we could do with explaining the difference between the two.

3. Formatting is having a rough one

Is the whitespace meaningful or do you mind me sending a PR to tidy it up?

I dont want to make loads of conflicts but it does need doing.

4. Is apis.txt beign dropped?

Early in the document there's mention of apis.txt and later in the document it says:

It is intended that if there is sufficient traction, the "well known" location "/apis.json" or "/apis.yaml" will be submitted as per RFC...

Should the mention of apis.txt be removed? Do we know if anyone is actually using .txt?

5. Is humanUrl & baseUrl mandatory or optional

Other properties all seem to be marked as mandatory or optional but these are not marked. A quick scan shows all others are covered its just these two. I'm going to assume optional for the article I'm writing but lmk if I'm wrong.

6. What is the YAML media-type?

I see some mentions of "application/apis+yaml" and some mentions of "application/x-yaml" but I presume the first one is correct?

[kinlane]

Hey Phil -- appreciate the feedback.

Let me take a crack at it:

1. Define type values - Agreed, I will flesh out more. Steve hates this property. Calls it junk drawer.
2. Related to 1, two mentions of Blueprint - Yeah, Apiary's API Blueprint, I will better articulate. Would prefer to remove, but will wait until 1.0. Sadly it isn't a contender anymore.
3. Formatting is having a rough one - Yeah, needs some love. I will address with next round of work--will clean up across them.
4. Is apis.txt beign dropped? - No, just need to be more consistent. Will update.

I'll leave this issue open for when I do then next push on spec either this weekend or next.

Hope all is well my friend!!

[philsturgeon]

Doing good! I poked you on APIs You Wont Hate Slack for a catchup as its been bloomin ages.

1. Ha!
2. Yeah I figured ditch API Blueprint from Property Elements but was keeping opinions to a minimum (a new thing I'm trying, feels weird)
3. Cheers
4. Ta.

Added a 5 in but I seem to be getting close to done on feedback.

This is really cool, and I'm excited to see it being picked up by tooling vendors, with Bump.sh rolling out support (given them some feedback to improve also ofc)

Example: https://bump.sh/green-turtle/hub/tree-tracker/apis.json

[kinlane]

Nice! Thanks for sharing. I'll jump on Slack -- haven't had on at home since Postman, but will fire back up. ;-) Would love to catch up.

[kinlane]

Adding Bump to the list of vendors supporting:

• SwaggerHub Search API - https://app.swaggerhub.com/apis/swagger-hub/registry-api/1.0.67#/APIs/searchApisAndDomains
• Kiota SDK - https://learn.microsoft.com/en-us/openapi/kiota/add-api
• Bump - https://bump.sh/green-turtle/hub/tree-tracker/apis.json

It's a start!