Add HTTP Gateway Specs

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Spec Stewards defined below are automatically requested for review when
+# someone opens a pull request that modifies area of their interest.
+
+http-gateways/  @lidel

README.md

@@ -29,14 +29,12 @@ The specs contained in this repository are:
   - [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack
   - [Other IPFS Overviews](/overviews) - quick overviews of the various parts of IPFS
 - **User Interface (aka Public APIs):**
-  - [Core API (aka using IPFS as a package/module)](./API_CORE.md)
-    - [JavaScript Interface](https://github.com/ipfs/interface-js-ipfs-core)
-    - [Golang Interface](https://github.com/ipfs/interface-go-ipfs-core)
-  - [CLI (the ipfs daemon API)](./API_CLI.md)
-  - [HTTP API](./API_HTTP.md)
-  - HTTP Gateway
+  - [HTTP Gateways](./http-gateways/README.md) - implementation agnostic interfaces for accessing content-addressed data over HTTP
+  - IPFS implementations may provide additional interfaces, for example:
+    - [HTTP RPC API exposed by go-ipfs](https://docs.ipfs.io/reference/http/api/)
+    - [Programmatic Core API for JavaScript](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api#readme)
 - **Data Formats:**
-  - [IPLD](https://github.com/ipld/spec) - InterPlanetary Linked Data.
+  - [IPLD](https://ipld.io/specs/) - InterPlanetary Linked Data.
   - [Merkle DAG (Deprecated)](./MERKLE_DAG.md)
   - Self Describing Formats ([multiformats](http://github.com/multiformats/multiformats)):
     - [multihash](https://github.com/multiformats/multihash) - self-describing hash digest format.

http-gateways/DNSLINK_GATEWAY.md

@@ -0,0 +1,76 @@
+# DNSLink Gateway Specification
+
+![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
+
+**Authors**:
+
+- Marcin Rataj ([@lidel](https://github.com/lidel))
+
+----
+
+**Abstract**
+
+DNSLink Gateway is an extension of
+[PATH_GATEWAY.md](./PATH_GATEWAY.md)
+that enables hosting a specific content path under a specific DNS name.
+
+This document describes the delta between [PATH_GATEWAY.md](./PATH_GATEWAY.md) and this gateway type.
+
+In short:
+
+- HTTP request includes a valid DNSLink name in `Host` header
+- gateway resolves DNSLink to an immutable content root identified by a CID
+- HTTP response includes the data for the CID
+- No third-party CIDs can be loaded
+
+# Table of Contents
+
+- [DNSLink Gateway Specification](#dnslink-gateway-specification)
+- [Table of Contents](#table-of-contents)
+- [HTTP API](#http-api)
+  - [`GET /[{path}][?{params}]`](#get-pathparams)
+  - [`HEAD /[{path}][?{params}]`](#head-pathparams)
+- [HTTP Request](#http-request)
+  - [Request headers](#request-headers)
+    - [`Host` (request header)](#host-request-header)
+- [Appendix: notes for implementers](#appendix-notes-for-implementers)
+  - [Leveraging DNS for content routing](#leveraging-dns-for-content-routing)
+
+# HTTP API
+
+## `GET /[{path}][?{params}]`
+
+Downloads data at specified path under the content path for DNSLink name provided in `Host` header. 
+
+- `path` – optional path to a file or a directory under the content root sent in `Host` HTTP header
+    - Example: if `Host: example.com` then the content path to resolve is `/ipns/example.com/{path}`
+
+## `HEAD /[{path}][?{params}]`
+
+Same as GET, but does not return any payload.
+
+# HTTP Request
+
+## Request headers
+
+### `Host` (request header)
+
+
+Defines the DNSLink name to resolve into `/ipfs/{cid}/` prefix that should be
+prepended to the `path` before the final IPFS content path resolution is
+performed.
+
+Example: if client sent HTTP GET request for `/sub-path` path and  `Host:
+example.com` header, and DNS at `_dnslink.example.com` has TXT record with
+value  `dnslink=/ipfs/cid1`, then the final content path is
+`/ipfs/cid1/sub-path`
+
+# Appendix: notes for implementers
+
+## Leveraging DNS for content routing
+
+- It is a good idea to publish
+  [DNSAddr](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md)
+  TXT records with known content providers for the data behind a DNSLink. IPFS
+  clients will be able to detect DNSAddr and preconnect to known content
+  providers, removing the need for expensive DHT lookup.