Hacker News Reader

Comment by jetti | Hacker News Reader

I have some feedback from reading your docs.

1.) Don't use httpie for the examples. It isn't standard and it is confusing for those who have no experience with it. I had to navigate to the httpie website to see how the tool works just to look at your documentation because you say that JSON is required but your documentation doesn't use valid JSON because httpie does the work for you. I would suggest using curl for the examples.

2.) I'm curious as to why you are using POST for almost all the requests.

3.) Are you adding more endpoints to this service? I'm curious the motivation behind the current functionality as most of it seems to be very niche in how applicable it is.

View on HN

Thanks for taking the time to read and go write this super beneficial feedback Jetti!

1.) The reason why I choose httpie over curl is that it is a lot shorter and just show the essential instead of setting the applicaton/json and having json as a string, but you're right. I'll translate all the examples to curl in the next coming time.

2.) The APIs do not fit the standard CRUD/Resource (Rest) approach. Our small team discussed a lot about how to do it and tried different ways but it made it harder to remember was it with a POST, or GET? Both kinda made sense, and what when you wanted parameters with as GET?

3.) We will be adding a tonne. First, we wanted the platform up and running as basic as possible. We got inspired by the "API Marketplaces" where everyone can upload an API, but we want to address the problems with poor quality, latency, and documentation. The idea is to have one place to use/pay/do.

Almost nobody signed up compared to the visitors we got from HN. Can I ask you if you signed up or not and how come?

As for number 2, I think it may be more confusing for potential users since it doesn’t follow a pattern that is typical.

I did not sign up. I don’t have any need for anything you provide at the moment. I think some of the endpoints are going to be very niche. I have never needed to post anything to pastebin. Most languages provide functionality for a UUID as well.

Thanks again Jetti!

Reply on news.ycombinator.com