5 ms·

What should be the goals of creating an open discussion around an API spec?

24 points by zende 14y ago

knighthacker 14y ago
The two biggest goals in my mind would be: 1) You involve the API consumers in the design and decision process, which helps in understanding their use cases better. 2) Give insights and transparency to consumers as to why and how some decisions were made about the API.
- zende 14y ago
  Should also be a great start to improve the API docs (https://www.balancedpayments.com/docs/api https://www.balancedpayments.com/docs/api)
  - deleted 14y ago
    [deleted]
  - deleted 14y ago
    [deleted]
  - deleted 14y ago
    [deleted]
  - deleted 14y ago
    [deleted]
  - deleted 14y ago
    [deleted]
  - deleted 14y ago
    [deleted]
  - samratjp 14y ago
    It'd be nice to be able fork or even comment the API docs as a developer using the API. Tooo many times I googled for an answer that the API docs neglect and found the answer instead on StackOverflow. If I had a facebook credit for every time I found the answer I was looking for with facebook's API docs, I'd be pretty poor :-p
    - zende 14y ago
      > It'd be nice to be able fork or even comment the API docs as a developer using the API You want to comment on the API docs using the API itself? The goal is to let you fork the specs and issue a pull request on GitHub. > Tooo many times I googled for an answer that the API docs neglect and found the answer instead on StackOverflow. Are you referring to the API docs for Balanced or API docs in general?
      - samratjp 14y ago
        (Sorry didn't realize this was actually linked to the github discussion/thought it was an Ask HN) Forking the specs sounds good. Meant the lacking in answers for API docs in general. Especially facebook in the past; though Graph Explorer is much nicer!
mahmoudimus 14y ago
One of the goals should be the guarantees given that the API spec that's documented is actually reflected on the live version and the steps taken to ensure its accuracy.
deleted 14y ago
[deleted]
pulledpork 14y ago
I like the idea of contributing but it would be nice if I could give a simple up vote rather than having to add a full comment. You may get weighed down by "me too +1" comments.
- zende 14y ago
  "+1" or "yes" appear to be the norm on GitHub. Example: https://github.com/hotsh/rstat.us/pull/443 https://github.com/hotsh/rstat.us/pull/443
mjallday 14y ago
How would you deal with the issue of having to respond to everybody's comments, this could end up being a time sink. E.g. you write a beautiful proposal on some new feature and then joe schmoe comes along and shits on your idea without taking time to consider it. Now you have to either ignore his comment, leaving it there for other schmoes to read, or respond to it which takes time away from doing something constructive.
- zende 14y ago
  GitHub lets the repo owner/maintainer delete other people's comments. Strangely, they appear to also allow the repo owner edit other people's comments, which I don't really get.
T_S_ 14y ago
"Embrace and extend." -- Bill Gates These days that would correspond to forking the spec. So unlike an open source programming, it is not nice to fork the spec. Or is it?
- zende 14y ago
  Forking the specs for an API feels just like forking an open source project. I wouldn't want to drudge through Facebook's API code, but it would be nice to comment on changes, have a changelog, and make them auto validate against their own specs.

24 points by zende 14y ago

The two biggest goals in my mind would be: 1) You involve the API consumers in the design and decision process, which helps in understanding their use cases better. 2) Give insights and transparency to consumers as to why and how some decisions were made about the API.

zende 14y ago
Should also be a great start to improve the API docs (https://www.balancedpayments.com/docs/api https://www.balancedpayments.com/docs/api)
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- deleted 14y ago
  [deleted]
- samratjp 14y ago
  It'd be nice to be able fork or even comment the API docs as a developer using the API. Tooo many times I googled for an answer that the API docs neglect and found the answer instead on StackOverflow. If I had a facebook credit for every time I found the answer I was looking for with facebook's API docs, I'd be pretty poor :-p
  - zende 14y ago
    > It'd be nice to be able fork or even comment the API docs as a developer using the API You want to comment on the API docs using the API itself? The goal is to let you fork the specs and issue a pull request on GitHub. > Tooo many times I googled for an answer that the API docs neglect and found the answer instead on StackOverflow. Are you referring to the API docs for Balanced or API docs in general?
    - samratjp 14y ago
      (Sorry didn't realize this was actually linked to the github discussion/thought it was an Ask HN) Forking the specs sounds good. Meant the lacking in answers for API docs in general. Especially facebook in the past; though Graph Explorer is much nicer!

mahmoudimus 14y ago

One of the goals should be the guarantees given that the API spec that's documented is actually reflected on the live version and the steps taken to ensure its accuracy.

deleted 14y ago

[deleted]

pulledpork 14y ago

I like the idea of contributing but it would be nice if I could give a simple up vote rather than having to add a full comment. You may get weighed down by "me too +1" comments.

zende 14y ago
"+1" or "yes" appear to be the norm on GitHub. Example: https://github.com/hotsh/rstat.us/pull/443 https://github.com/hotsh/rstat.us/pull/443

mjallday 14y ago

How would you deal with the issue of having to respond to everybody's comments, this could end up being a time sink. E.g. you write a beautiful proposal on some new feature and then joe schmoe comes along and shits on your idea without taking time to consider it. Now you have to either ignore his comment, leaving it there for other schmoes to read, or respond to it which takes time away from doing something constructive.

zende 14y ago
GitHub lets the repo owner/maintainer delete other people's comments. Strangely, they appear to also allow the repo owner edit other people's comments, which I don't really get.

T_S_ 14y ago

"Embrace and extend." -- Bill Gates These days that would correspond to forking the spec. So unlike an open source programming, it is not nice to fork the spec. Or is it?

zende 14y ago
Forking the specs for an API feels just like forking an open source project. I wouldn't want to drudge through Facebook's API code, but it would be nice to comment on changes, have a changelog, and make them auto validate against their own specs.