provide a clear, linkable path for finding the core API docs

API/README.md

@@ -0,0 +1,3 @@
+# IPFS Core API
+
+This directory contains the description of the core IPFS API. In order to be considered "valid", an IPFS core implementation must expose the API described here. You can also use this loose spec as documentation for consuming the core APIs. Ther is an outline of the contents of that directory in the [API section of this repository's root README file](../README.md#api).

README.md

@@ -17,54 +17,6 @@
   - [Node.js](#nodejs)
   - [Go](#go)
 - [API](#api)
-  - [bitswap (not spec'ed yet)](/API/bitswap)
-  - [block](/API/block)
-    - [`block.get`](/API/block#get)
-    - [`block.put`](/API/block#put)
-    - [`block.stat`](/API/block#stat)
-  - [bootstrap](/API/bootstrap)
-  - [config](/API/config)
-    - [`config.get`](/API/config#get)
-    - [`config.set`](/API/config#set)
-    - [`config.replace`](/API/config#replace)
-  - [dag](/API/dag)
-    - [`dag.put`](/API/dag#dagput)
-    - [`dag.get`](/API/dag#dagget)
-    - [`dag.tree`](/API/dag#dagtree)
-  - [dht (not spec'ed yet)](/API/dht)
-  - [files](/API/files)
-    - [`add`](/API/files#add)
-    - [`createAddStream`](/files#createaddstream)
-    - [`get`](/API/files#get)
-    - [`cat`](/API/files#cat)
-  - [generic operations](/API/generic)
-    - [`id`](/API/generic#id)
-    - [`version`](/API/generic#version)
-  - [object](/API/object)
-    - [`object.new`](/API/object#objectnew)
-    - [`object.put`](/API/object#objectput)
-    - [`object.get`](/API/object#objectget)
-    - [`object.data`](/API/object#objectdata)
-    - [`object.links`](/API/object#objectlinks)
-    - [`object.stat`](/API/object#objectstat)
-    - [`object.patch`](/API/object#objectpatch)
-      - [`object.patch.addLink`](/API/object#objectpatchaddlink)
-      - [`object.patch.rmLink`](/API/object#objectpatchrmlink)
-      - [`object.patch.appendData`](/API/object#objectpatchappenddata)
-      - [`object.patch.setData`](/API/object#objectpatchsetdata)
-  - [pin (not spec'ed yet)](/API/pin)
-  - [pubsub](/API/pubsub)
-    - [`pubsub.subscribe`](/API/pubsub#pubsubsubscribe)
-    - [`pubsub.unsubscribe`](/API/pubsub#pubsubunsubscribe)
-    - [`pubsub.publish`](/API/pubsub#pubsubpublish)
-    - [`pubsub.ls`](/API/pubsub#pubsubls)
-    - [`pubsub.peers`](/API/pubsub#pubsubpeers)
-  - [repo (not spec'ed yet)](/API/repo)
-  - [swarm](/API/swarm)
-    - [`swarm.addrs`](/API/swarm#addrs)
-    - [`swarm.connect`](/API/swarm#connect)
-    - [`swarm.disconnect`](/API/swarm#disconnect)
-    - [`swarm.peers`](/API/swarm#peers)
 - [Contribute](#contribute)
   - [Want to hack on IPFS?](#want-to-hack-on-ipfs)
 - [License](#license)
@@ -131,7 +83,56 @@ test.all(common)
 
 ## API
 
-A valid (read: that follows this interface) IPFS core implementation must expose the API described in [/API](/API).
+In order to be considered "valid", an IPFS core implementation  must expose the API described in [/API](/API). You can also use this loose spec as documentation for consuming the core APIs. Here is an outline of the contents of that directory:
+
+- [bitswap (not spec'ed yet)](/API/bitswap)
+- [block](/API/block)
+  - [`block.get`](/API/block#get)
+  - [`block.put`](/API/block#put)
+  - [`block.stat`](/API/block#stat)
+- [bootstrap](/API/bootstrap)
+- [config](/API/config)
+  - [`config.get`](/API/config#get)
+  - [`config.set`](/API/config#set)
+  - [`config.replace`](/API/config#replace)
+- [dag](/API/dag)
+  - [`dag.put`](/API/dag#dagput)
+  - [`dag.get`](/API/dag#dagget)
+  - [`dag.tree`](/API/dag#dagtree)
+- [dht (not spec'ed yet)](/API/dht)
+- [files](/API/files)
+  - [`add`](/API/files#add)
+  - [`createAddStream`](/files#createaddstream)
+  - [`get`](/API/files#get)
+  - [`cat`](/API/files#cat)
+- [generic operations](/API/generic)
+  - [`id`](/API/generic#id)
+  - [`version`](/API/generic#version)
+- [object](/API/object)
+  - [`object.new`](/API/object#objectnew)
+  - [`object.put`](/API/object#objectput)
+  - [`object.get`](/API/object#objectget)
+  - [`object.data`](/API/object#objectdata)
+  - [`object.links`](/API/object#objectlinks)
+  - [`object.stat`](/API/object#objectstat)
+  - [`object.patch`](/API/object#objectpatch)
+    - [`object.patch.addLink`](/API/object#objectpatchaddlink)
+    - [`object.patch.rmLink`](/API/object#objectpatchrmlink)
+    - [`object.patch.appendData`](/API/object#objectpatchappenddata)
+    - [`object.patch.setData`](/API/object#objectpatchsetdata)
+- [pin (not spec'ed yet)](/API/pin)
+- [pubsub](/API/pubsub)
+  - [`pubsub.subscribe`](/API/pubsub#pubsubsubscribe)
+  - [`pubsub.unsubscribe`](/API/pubsub#pubsubunsubscribe)
+  - [`pubsub.publish`](/API/pubsub#pubsubpublish)
+  - [`pubsub.ls`](/API/pubsub#pubsubls)
+  - [`pubsub.peers`](/API/pubsub#pubsubpeers)
+- [repo (not spec'ed yet)](/API/repo)
+- [swarm](/API/swarm)
+  - [`swarm.addrs`](/API/swarm#addrs)
+  - [`swarm.connect`](/API/swarm#connect)
+  - [`swarm.disconnect`](/API/swarm#disconnect)
+  - [`swarm.peers`](/API/swarm#peers)
 
 ## Contribute