Can we rename the repo to "http-api-apiary-format"

[daviddias]

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

[dignifiedquire]

I would be okay with http-api, but http-api-apiary-format is a bit over the top for my taste.

[daviddias]

http-api is part of the specs repo, this repo will only contain a format that is compatible with apiary

[dignifiedquire]

ok :(

[daviddias]

@RichardLitt do you agree? Thoughts?

[RichardLitt]

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. http-api would be ok, too. The implementation is what is currently in master; the adjustments to fit an ideal specification is what we will be working on in patches. Make sense?

[daviddias]

then, what about http-api-spec?

[dignifiedquire]

🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠 🚲 🏠

[RichardLitt]

@diasdavid This isn't just a spec, though, or it would be in specs.

Better question: Is there any reason you want the api namespace open? This repo should house anything related to the API which is not in specs or the original go-ipfs, js-ipfs repos.

[jbenet]

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
it?
On Mon, Jan 11, 2016 at 16:49 Richard Littauer [email protected]
wrote:

@diasdavid https://github.com/diasdavid This isn't just a spec, though,
or it would be in specs.

Better question: Is there any reason you want the api namespace open?
This repo should house anything related to the API which is not in specs or
the original go-ipfs, js-ipfs repos.

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

[RichardLitt]

Apiary doesn't exclude other stuff being in this repo.

[daviddias]

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

[RichardLitt]

@diasdavid What is confusing? What would you like the api namespace for? What tools do you think ought to belong in an api repo?

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?

[daviddias]

note: I didn't expect that this would generate such a long discussion, but seems good that we started it and get to clarify some points on how things tie together :)

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:

• Core API - The API that is accessible by importing IPFS as a module, for example https://ipfs.io/ipfs/QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/example#/ipfs/QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7/api/service/readme.md, or when someone imports IPFS to use it own the browser.
• HTTP-API - Our RPC over HTTP, the API that is being documented on this repo.
• CLI API - The command line interface that IPFS offers (which inside uses the HTTP-API to talk with IPFS)

Having this clarified:

Specs go in specs, and the api endpoints go in go-ipfs and node-ipfs.

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.

What would you like the api namespace for?

I just feel that the name is too generic and can easily mislead people coming to the repo.

[RichardLitt]

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 $ ipfs?

This is the Core API

It is unclear what this refers to, here. Again, apologies for asking, but what do you mean there?

...eventually it will be standardised...

Where? That ought to be here, I think. What would that standardization look like?

I just feel that the name is too generic and can easily mislead people coming to the repo.

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?

[jbenet]

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.

[jbenet]

more:

• the "core api" is an interface defining what an IPFS node should do. it's the thing we were writing out altogether (with @dignifiedquire and others) in a hangout.
• this "core api" in turn is implement in go-ipfs (as "the go-ipfs core api") and in js-ipfs (as "the js-ipfs core api"), and can be used programmatically as a library by importing the packages.
• the "core api" in turn defines what the other apis ("http api" and "cli api") can do. these others may be supersets or subsets, but they part from the "core api".
• the "http api" is "exposing the core api over http" and includes other stuff. what's getting speced here.
• the "cli api" is "exposing the core api over unix shell commands" -- and yes, it's the $ ipfs add, cat, ls, ... commands.

hope this helps?

[daviddias]

• the "core api" is an interface defining what an IPFS node should do. it's the thing we were writing out altogether (with @dignifiedquire and others) in a hangout.

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 :)

[RichardLitt]

@diasdavid Cool. Yes, that makes more sense. Thanks for being patient with me. :)

[daviddias]

awesome :D :D I believe we reached the quorum to rename it to http-api-spec then :) changing it :D

[RichardLitt]

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.

[RichardLitt]

The reason this is relevant is that it affects the name of the repo. I think the name should not be http-api-spec if the spec file isn't here. http-api works if the spec file is, too. http-api-description or http-api-doc or something is better suited for the current functionality.

[RichardLitt]

cc @diasdavid

[daviddias]

Currently, http-api state (how it is working currently), lives here. For context, as we discussed (sprint meetings + in person), once this documentation ends, we will work in a PR and per endpoint basis, fixing each HTTP-API endpoint and opening issues/PR on go-ipfs to fix its API.

[dignifiedquire]

So what's the name you want to use now?