-
Notifications
You must be signed in to change notification settings - Fork 22
Can we rename the repo to "http-api-apiary-format" #19
Comments
I would be okay with |
|
ok :( |
@RichardLitt do you agree? Thoughts? |
I don't think that we should confine it to apiary - apiary is the format, which doesn't need to be in the title. Sort of like how we don't have website repos called 'website-html'. I think 'http-api' works just fine. Seeing as how this is both the spec and the current functionality, we should keep it as http. |
then, what about http-api-spec? |
🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 |
@diasdavid This isn't just a spec, though, or it would be in specs. Better question: Is there any reason you want the |
Agree with Richard. Original goal was to have more stuff here. Or does apiary make it impossible, forcing the repo to be dedicated only to
|
Apiary doesn't exclude other stuff being in this repo. |
Original goal was to have API specs in this repo (or it started when @dignifiedquire opened it to make it work on Apiary and then it was moved here) then it was discussed and agreed on one of the IPFS Sprint Meetings in December that we would move the specs to specs repo, so that it continues easy to find and keeps everything organised. More context can be found here: #11 Currently, this repo, only contains the HTTP API description, made in the format that Apiary expects, so that it works with their tooling, it doesn't hold any of the core API (programmatic interface), nor the CLI. That was moved, as agreed, to: https://github.com/ipfs/specs/tree/master/api and under update here: ipfs/specs#65 |
@diasdavid What is confusing? What would you like the Specs go in specs, and the api endpoints go in go-ipfs and node-ipfs. Everything else related to the API should go in here. I'm having some issues understanding your position. Do you think that another repo should hold the core api interface, or the CLI? What would that look like? |
It would good for the purposes of this discussion, that we start being more explicit when we want to refer to the several apis, namely:
Having this clarified:
This is the Core API, and although there is no active work on standardizing it, other than our "interface-{transport, connection, stream-muxer, peer-routing, record-store}", because it is very in flux and no one is necessarily depending on it right now, but eventually it will be standardised so that developers can build applications embeding IPFS and trust that the core API will remain stable.
I just feel that the name is too generic and can easily mislead people coming to the repo. |
Agreed about defining terms. I went for a run and thought about it, and I think that this particular bikeshed is a bit of an ego-sink for me, because the terms have not been clearly defined and I've put a lot of processing into circular systems here. I understand what you mean by Core API in the first case; that is certainly not in this repo. I do not understand how the CLI API uses the HTTP API, or what the CLI API is. You mean the CLI commands that I know of as
It is unclear what this refers to, here. Again, apologies for asking, but what do you mean there?
Where? That ought to be here, I think. What would that standardization look like?
Let's pretend it is six months from now. What else would we like to have, regarding documentation and APIs? Is there any chance that we won't change this back? |
yeah @diasdavid is right. +1 on "core api" "http api" and "cli api"
distinctions.
one goal was to have "the core api" speced out in a repo somewhere. we can
put that in specs, though we began that work here i think.
|
more:
hope this helps? |
Check https://github.com/ipfs/specs/pull/65/files , specially the https://github.com/ipfs/specs/blob/ipfs/api/api/core/README.md @RichardLitt I believe @jbenet answered your questions, let me know if there is still any question :) |
@diasdavid Cool. Yes, that makes more sense. Thanks for being patient with me. :) |
awesome :D :D I believe we reached the quorum to rename it to |
Sorry, was just commenting when you closed it. You know, I'm still not sure about this. This repo is for the apiary format. However, we have a poor workflow around that. Currently, the master branch has an empty file. What I do then is I stub out the current API responses and status in another branch, and then PR into master. That PR then gets two types of comments: the first finding issues in my description, the second finding issues in the implementation. Ideally, only the first are dealt with, and then we merge. However, I then should make a second PR with only the second issues, and reference issues on go-ipfs about how to fix the implementation. This creates a lot of friction. A much cleaner system would be to have two files: a current description, and a spec, also in apiary format. Any issues to the spec can be dealt with in their own issues, and any differences between spec and current implementation can be mentioned in their own relative PRs. This would mean that it would be much easier to spec out the current implementation without the friction of having people comment on issues which they really have with the spec, not with my description of the current implementation. Proposal: Let's move the HTTP API specification here, in it's entirety. Then, we can have two files: spec.apib, and implementation.apib. Alternate proposal: Let's delete this repository, and move the current implementation into specs. I think this would lead to a lot of noise in ipfs/specs, though. |
The reason this is relevant is that it affects the name of the repo. I think the name should not be |
cc @diasdavid |
Currently, |
So what's the name you want to use now? |
Sorry to nick pick, I just feel that
api
suggests a whole set of things that this repo is not and is is hard to go from from "api" to "the http-api description in apiary format", which is what it is :)Also added more stuff to the readme to point to the real spec -> #18
The text was updated successfully, but these errors were encountered: