Better UX for listing

[kyyberi]

Github is nice but UX in this case is not the ideal IMHO. I did experimental listing of APIs with jQuery. Not fully implemented or too fancy, contains bugs and error handling etc but something like this would make browsing and discoverability a little better.

http://apisuomi.fi:8080/apis/apis.guru/

If such (average) human readable front is created, it might make sense to use some lightweight JS framework.

[kyyberi]

I wrote earlier this year a few words about "APIverse", an offspring of thingiverse.com. APIverse would be the place to share API specs much like thingiverse is for sharing digital 3d printable files. http://apisuomi.fi/2015/09/apiverse-thingiverse-for-apis/

[IvanGoncharov]

@kyyberi I read your article and it's very similar to what I had in my mind as roadmap for this project.
If you have couple of minutes I like to show you few slides and hear your opinion.
We can do this over Skype(ivangon4arov) or Hangout(ivan.goncharov.ua@gmail.com)

[IvanGoncharov]

@kyyberi About UX for this project, I totally agree that it require some simple UX.
I'm not a Web developer so it's hard to write something decent.
But I like your prototype and gladly accept any contribution.

About framework I prefered to do it KISS style.
I have some early prototype contributed by @RomanGotsiy as #23.
What do you think about doing it as static HTML generated per-commit by index.jade?
It hosted on https://apis-guru.github.io/api-models/
But I own APIs.guru domain name so I can setup redirection.

[kyyberi]

Excellent! I'm currently on vacation and return to more active state after New Year. Let's fix a date for online meeting via email. I'll contact you to start a thread.

[IvanGoncharov]

@kyyberi 👍

[IvanGoncharov]

@kyyberi Happy holidays 🎄 🎅 ⛄

[IvanGoncharov]

@kyyberi I added new banner in SVG format you can use it in your UX:

[kyyberi]

ok, thanks @IvanGoncharov. In use now.

[IvanGoncharov]

@kyyberi One thing I noted is that you don't use backgroundColor property, it preset for all images that need it. For example here.

[kyyberi]

Good point. Although I'm using https://apis-guru.github.io/api-models/apis.json for all the information. Reading all specs just to list items would be overkill IMHO. Perhaps the backgroundColor property could be added to apis.json listing?

[IvanGoncharov]

@kyyberi Yes I can extend apis.json if required but entire format is somewhat limiting.
In a sense that it duplicate many fields from Swagger format but also missing many useful things.
So I need to create vendor extensions for both formats which is not what I really like to do.
Thats is why I created my own API where I simply copy info section from Swagger file.

I think it simplify usage flow for many potential clients because you need to present both catalog view with all APIs and individual API when user click on it.
In both cases you can use same code which interpreted Swagger's info section with my vendor extensions.

As bonus feature in my API I group different versions of same API and also mark prefered one.
And I thinks it general trend, format should be inline with catalog structure to really expose all features.

[IvanGoncharov]

@kyyberi But I totally open for discussion if you know some cons of this approach.

[kyyberi]

Your API approach seems legit.

[IvanGoncharov]

Hi @kyyberi

I liked idea of UI so much that I asked @yegorov-andrey to help me.
And he used some ideas from your prototype and create this one: http://apis-guru.github.io/
It made with Bootstrap and JQuery, repo is here: https://github.com/APIs-guru/APIs-guru.github.io
What do you think?

[rbren]

This looks great Ivan!

One small nit - Bootstrap's cols should always be wrapped in rows. This is
why the left/right edge of the API boxes aren't lined up with the top
banner (see image). Would send a PR but it looks like index.html on the
gh-pages branch is auto-generated.

​

Bobby Brennan
bobby.brennan@gmail.com

On Wed, Feb 10, 2016 at 7:22 PM, Ivan Goncharov notifications@github.com
wrote:

Hi @kyyberi https://github.com/kyyberi

I liked idea of UI so much that I asked @yegorov-andrey
https://github.com/yegorov-andrey to help me.
And he used some ideas from your prototype and create this one:
http://apis-guru.github.io/
It made with Bootstrap and JQuery, repo is here:
https://github.com/APIs-guru/APIs-guru.github.io
What do you think?

—
Reply to this email directly or view it on GitHub
#31 (comment)
.

[rbren]

[kyyberi]

Hei

On ke, 2016-02-10 at 16:22 -0800, Ivan Goncharov wrote:

Hi @kyyberi

I liked idea of UI so much that I asked @yegorov-andrey to help me.
And he used some ideas from your prototype and create this one:
http://apis-guru.github.io/
It made with Bootstrap and JQuery, repo is here:
https://github.com/APIs-guru/APIs-guru.github.io
What do you think?

Excellent! Great improvements! This is how community development
works :)

—
Reply to this email directly or view it on GitHub.

[yegorov-andrey]

One small nit - Bootstrap's cols should always be wrapped in rows. This is
why the left/right edge of the API boxes aren't lined up with the top
banner (see image). Would send a PR but it looks like index.html on the
gh-pages branch is auto-generated.

Hi, @bobby-brennan
I have used ".container" for header and api cards (cells) also put in ".container" ("#list") (https://github.com/APIs-guru/APIs-guru.github.io/blob/master/index.html). I have quite small experience in html, css, bootstrap css and jquery.
It appeared that there is no need for gh-pages branch for <username>.github.io repository (https://pages.github.com/). So, entire site is in master branch (https://github.com/APIs-guru/APIs-guru.github.io).
Will be appreciated for your thoughts about implementation or PRs.
Thanks :)

[yegorov-andrey]

@bobby-brennan, tried to change .container to .row and added padding: 0 50px; for <body>, but received the same result.

[rbren]

Thanks! Here's what I mean:

APIs-guru/APIs-guru.github.io#1

Haven't tested, but that should get everything lined up nicely.

Bobby Brennan
bobby.brennan@gmail.com

On Thu, Feb 11, 2016 at 2:50 PM, yegorov-andrey notifications@github.com
wrote:

@bobby-brennan https://github.com/bobby-brennan, tried to change
.container to .row and added padding: 0 50px; for , but received
the same result.

—
Reply to this email directly or view it on GitHub
#31 (comment)
.

[yegorov-andrey]

Thanks @bobby-brennan!
Looks great now.
May be we should align footer to the header?

[yegorov-andrey]

Aligned footer width with header width.

[IvanGoncharov]

I think @yegorov-andrey done a good job in implementing feature requested in this issue.
So I close it, but if someone have suggestion or ideas feel free to open issue in UI repo:
https://github.com/APIs-guru/APIs-guru.github.io