Feature Request: API Elements

[philsturgeon]

Howdy!

This is a bit of a big one, but theoretically it would not be a task entirely on your shoulders.

The Apiary folks have done a fair bit of work on API Elements, to help them build out tooling around both OpenAPI and their own API Blueprint format. They found that supporting both languages directly in their code was a giant effort, so they built this abstraction layer to improve things.

I bring it up here, because the entire API specification ecosystem could really benefit from ReDoc supporting API Elements instead of OpenAPI directly. It would not only solve #312 (and split the burden of upgrading OAI in the future), but it would bring a bunch of users this way due to API Blueprint lacking an actively maintained doc renderer.

Snowboard and Aglio are both way behind in features, functionality, looks, and... every other metric. Data structures are a total hack for Aglio sadly.

I don't want to speak for Apiary people, but it's my impression they'd be into working on this with you. I'm sure the React switch is going to take up a lot of your time, but I think if a bit of forward thinking was done into supporting API Elements you could make the React switch part of that effort.

API Elements and a lot of background on API Blueprint is kinda in this podcast if you're interested.

I'd love to see the API community come together with an excellent renderer that can support multiple formats, to help avoid vendor lockin and split the work of turning metadata into human viewable awesome docs.

[RomanHotsiy]

Hey @philsturgeon,

Thanks for bringing this up!
I was also contacted by @apiary-pythia about API Elements support in ReDoc btw.

I've considered this option from two perspectives:

• having this as an underlying data structure for ReDoc
• just supporting it

I've investigated into API Elements a bit and so far I won't introduce it as an underlying level:

• it's too verbose (just my personal opinion)
• potential performance issues (it relies on Refract and ReDoc has many users with huge specs)
• no native support for oneOf, discriminator and other complex patterns (while many ReDoc users rely on these heavily)
• no ready-to-use converters from other formats

Most likely I will have OpenAPI 3 as an underlying data structure or a bit modified version of it.
I am open to discussion though!

Regarding just supporting API Elements as a ReDoc input we can consider this in the future.
Btw, would just using "Blueprint to OpenAPI converter" fit your needs?

[philsturgeon]

Thanks for the explanation of all that! I'm not aware of Refract and what that means for performance issues, so I trust your judgement there. I'm glad you folks had the chat all the same.

My own needs were solved with APImatic Transformer and would in the future be probably better solved with https://github.com/luckymarmot/API-Flow, which does a similar thing to the tool you linked.

It's less about my needs, and more about "the API ecosystems needs". Whilst things can be converted from one format to another in a one-off fashion, it's usually a fairly lossy and imperfect process, and I'd not try to do it as part of a ongoing pipeline.

Really API Blueprint needs a decent renderer, and ReDoc is amazing. I hoped this would be a cool way to bring ReDoc into the fold, and break down a few walls in the various sub-ecosystems out there. :)

[RomanHotsiy]

Thanks for linking to API-Flow, it looks very interesting, I will definitely spend some time looking into it!

I see your points and they are really reasonable.

I think it would be great for ReDoc to support other formats so I will try to abstract OpenAPI from ReDoc core through some abstraction layer as much as possible (just to keep rewrite time reasonable). So in the future, we'll be able to finish this abstraction and just implement API Blueprint or other parser which will break down walls :)

[philsturgeon]

I’m really happy you’re into those ideas! It’s darn unfortunate that API Elements cannot be that abstraction layer though, that’s what it sets out to do! I wonder if there are others around.  Feel free to close this, or keep it for the “abstracting OpenAPI out” issue. Whichever!  Thanks for all the replies. 

[netmilk]

Hey! I'm the product manager for API Elements. I just wanted to share here a slightly modified version of the email I sent to @RomanGotsiy in response to his questions around API Elements

API Elements Data Structures does support oneOf. The API Elements are meant to be an abstract way of describing any data — not just JSON. That means they support most of the JSON schema functionality, but not all of it.

Fury.js — the wrapper for API Blueprint / OAS2 producing the API elements is currently partially converting basic JSON schemas from OAS2 documents to Data Structures. At this moment for the sake of rendering nice data structure documentation with Attributes Kit even for JSON schema - not only MSON.

The API description team is currently working on implementing the rest of the JSON Schema functionality. I can share the exact supported/unsupported/never-going-to-be-supported JSON Schema features later this week.

Performance of the Fury.js parser is going to be definitely lower than just parsing and dereferencing YAML documents because it’s doing more things. API Elements is decoupling our entire product from the API Description format hype/ecosystem/development and for instance, in case of implementing OAS3 - it’s just matter of creating a new adaptor for it and the format is introduced across the entire product surface. The same for RAML, Postman collections etc...

The parser is robust and actively maintained. It's handling huge documents (thousands LOCs) in the production Apiary already and we care about the performance of the parser a lot. Fury.js is an essential and heavily used component of the UX of the editor in Apiary - it validates the API description as-you-type in the editor with every other keystroke. We’re measuring basic performance continuously and we also monitor our internal parsing service and immediately react to any changes in the editor-parser-editor roundtrip time. Also, any exception in the production parser is causing an incident and our API description team is handling it as a production issue.

[RomanHotsiy]

Closing the issue:

• OpenAPI is definitely the dominating format right now and using API Elements will only complicate things for ReDoc
• There are converters from/to other formats and converter output can be always patched or fixed afterward manually