Some issues with v4

[stojsavljevic]

Hi,

I managed to embed api-console v4 in my app with help of front end architect from my company. After some time playing with v4 here is his feedback. Actually, some issues/pain points he encountered.

• bower is now used instead of npm
• missing dependency raml-js-parser
• lots of dependencies (bower generated dependency tree has 2694 lines; our distribution of api-console was 2,07MB and now it's 16,66MB)
• AngularJS and polymer (the entire stuff got more heavy)
• usage of web components that require custom JS (would prefer to have that as API of the console itself)
• some things in the api-console itself that might be redundant (e.g. some build related files like gruntfile.js that are probably not worth distributing when api-console is pulled in as a dependency)
• documentation could be better (some broken links, not that straightforward)

I hope you will find these points helpful. Overall, v4 looks awesome 😎 Thanks for the great work!

[jarrodek]

Hi,

Thank you for the issue report.

Bower

As you've noticed the API Console is made with web components. The npm registry and node architecture is not the best choice for the components. Node is a server side language and the components are to be used on a clients only. Because how node creates dependency tree, folder structure, you would never be able to manage dependencies in a efficient way. Bower is better enough to use it for web components. It creates flat directories structure so the same component is included only once whatever version was requested of the dependency. There's no such concept of components versioning in the web platform so a component can be registered only once. This also cause other problems when dependencies are having conflict but still I prefer to deal with this issue than complex directories structure.

For node applications it's not an issue anyway. You can use package.json file to create a build command for the console. I've described it here: https://github.com/mulesoft/api-console/issues/328#issuecomment-311501803

Missing parser

This is by design. Console do need data but it doesn't necessarily mean that it must be yaml. Yaml isn't platforms standard or native format and it requires additional code in the application to support this format. The goal of removing parser from the main code base of the console (or at least default release) is to minimize code size and to improve performance. Parsing RAML in browser will always lower the performance and there's very little we can do about this. So will did this little meaning removing the parser and replacing it with a json file with generated by the parser json output (and enhanced by our fork of raml2obj library. API Console build tools can generate this json file automatically from the API spec file and put it into console's generated sources or external files. See build tools docs for more information.

Generally this decision improved performance by a lot and did not caused any new limitations. As documented, you can include parser (and enhancer) in your project by calling bower install command. If you don't care about performance or you have specific use case that requires you to do it then we are not limiting you with this. As for now there's not plan for adding the parser to the default release of the console. And because of performance I doubt that this will happen. Though, it might be better documented.

Size of the Console

The size of the downloaded console is the size of the whole source code that resists on development machine. It contains a lot of not directly used in the console codes (test helpers, documentation helpers, components documentation and so on). Even if you'd send this whole directory to server only small portion of it would be downloaded to the browser. When you check network tab in Chrome Dev tools you'll notice that it downloaded about 4MB of code. But we still talking about raw source code. Polymer team have put lot of effort into building great tools to "build" the web components. I've used their tools to create the api-console-builder node module to automate the build process. With optimization options enabled (by default) size of the console drops to about 2MB and the console is concatenated to a single file (which can be good and bad depending on use case but this is not a place to discuss this). Anyway, this shouldn't be an issue if you use either ours or polymer's build tools for web components.

Polymer and angular

First of all angular is a framework and polymer is a library. Polymer mostly provides polyfills for web components (import spec, CSS variables, shadow Dom). It adds some sugar for web components but in version 2 of the library they decided to remove even those sugar functions and leave everything to the platform. Polymer is actually one of the smallest libraries out there (comparing to frameworks).

I hope that answers your question.

custom JS and Console's API

Not sure if I understand this once correctly. API Console exposes configuration options for hosting applications. It contains all the functionality that you can use. If there's something missing I'm ready to implement it. You don't have to care about the components. The API Console manages integration of them. Maybe if you cold give me an example of what you mean I could prepare a better answer

bower_components folder

Bower installs dependencies in bower_components folder. It's a developer folder like node_modules (more or less). Because the console should be optimized (see my comment about "building" the console) this shouldn't be an issue because you are not using it in production.

Gruntfile and some more files were included into the release by my mistake and those files are not used. Current release 4.1.0 has been cleaned.

Documentation

I agree that it could be better written. I'm not very skilled in writing a documentation and this was mine responsibility. I may give it another try soon but probably I'll find someone from the documentation team to update it and make it easier to understand.

Thanks for your concerns. Please let me know if there's anything else.

[jknack]

Like how v4 looks, lot more professional and ready for displaying lot of documentation, but I don't get all the complexity and effort required to for example embedded api-console in any other environment, except node.js.

To embedded v3 you just need 4 files (-theme.css, api-console-vendor.js, api-console.js, index.html). That's all and works as expected. If want to do the same with v4, don't know where to start.. but isn't about missing documentation or similar: it is just complex.

Also, seems api-console isn't able to read/parse RAML, anymore? So we need now another tool/process in the middle to convert .raml to .json? which again doesn't make sense for any other environment except node.js. Even more, I couldn't find any documentation about this .json format required by v4.

As said v4 looks very nice and professional, but developers should spend their time writing down RAML, not fighting with a tool.

Please try to simplify distribution, bootstrap and provide an option to read/parse RAML directly.

Thanks.

[jarrodek]

Hi,

Thank you for the comment. Please, read my previous comment to resolve all your issues.

For building the console to a single file: use build tools For RAML reading and using with console: build tools, passing RAML docs

I'm really listening to your comments here and from other channels and soon I'll spend some time trying to make it simpler for you to get the idea of Web Components, building process and passing the data. It is very important to us that developers don't have problems with adapting the console in their projects.

[jarrodek]

Version 5 and upcoming v6 has several improvements in this area. Version 5 comes with the CLI tool that allows to create a production ready bundle that can be customized for an environment. Version 6 comes with a build instruction for rollup and webpack so it can be built into existing application and a docker image with production ready console.

I am closing this issue as fixed.