From 4723ad6515d5f460d458f29d63b7fbb819527a3f Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 3 Dec 2021 21:48:54 +0100 Subject: [PATCH] feat: document RPC + Origin-based security This clarifies that the described API is RPC over HTTP, and informs how Origin-based security is applied in browser contexts. --- tools/http-api-docs/markdown.go | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/tools/http-api-docs/markdown.go b/tools/http-api-docs/markdown.go index 2cebfbfde..8d72efc47 100644 --- a/tools/http-api-docs/markdown.go +++ b/tools/http-api-docs/markdown.go @@ -17,20 +17,20 @@ type MarkdownFormatter struct{} func (md *MarkdownFormatter) GenerateIntro() string { buf := new(bytes.Buffer) fmt.Fprintf(buf, `--- -title: HTTP API +title: HTTP RPC API legacyUrl: https://docs.ipfs.io/reference/api/http/ -description: HTTP API reference for IPFS, the InterPlanetary File System. +description: HTTP RPC API reference for IPFS daemon. --- -# HTTP API reference +# HTTP RPC API reference _Generated on %s, from go-ipfs v%s._ -When an IPFS node is running as a daemon, it exposes an HTTP API that allows you to control the node and run the same commands you can from the command line. +When an IPFS node is running as a daemon, it exposes an HTTP RPC API that allows you to control the node and run the same commands you can from the command line. -In many cases, using this API this is preferable to embedding IPFS directly in your program — it allows you to maintain peer connections that are longer lived than your app and you can keep a single IPFS node running instead of several if your app can be launched multiple times. In fact, the `+"`ipfs`"+` CLI commands use this API when operating in online mode. +In many cases, using this RPC API is preferable to embedding IPFS directly in your program — it allows you to maintain peer connections that are longer lived than your app and you can keep a single IPFS node running instead of several if your app can be launched multiple times. In fact, the `+"`ipfs`"+` CLI commands use this RPC API when operating in online mode. ::: tip This document was autogenerated from go-ipfs. For issues and support, check out the [http-api-docs](https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs) repository on GitHub. @@ -42,7 +42,7 @@ This document was autogenerated from go-ipfs. For issues and support, check out The HTTP API under `+"`/api/v0/`"+` is an RPC-style API over HTTP, not a REST API. -[Every command](/reference/cli/) usable from the CLI is also available through the HTTP API. For example: +[Every command](/reference/cli/) usable from the CLI is also available through the HTTP RPC API. For example: `+"```sh"+ ` > ipfs swarm peers @@ -111,7 +111,6 @@ Additionally, as a convenience certain CLI commands may allow passing repeated f `+"`ipfs pin remote service ls --status=pinned,pinning`"+`; however, this does not apply to the HTTP API. ::: - ## HTTP status codes Status codes used at the RPC layer are simple: @@ -127,9 +126,14 @@ Status code `+"`500`"+` means that the function _does_ exist, but IPFS was not a Streaming endpoints fail as above, unless they have started streaming. That means they will have sent a `+"`200`"+` status code already. If an error happens during the stream, it will be included in a Trailer response header (some endpoints may additionally include an error in the last streamed object). -A `+"`405`"+`error may mean that you are using the wrong HTTP method (i.e. GET instead of POST), or that you are not allowed to call that method (i.e. due to CORS restrictions when making a request from a browser). +A `+"`405`"+` error may mean that you are using the wrong HTTP method (i.e. GET instead of POST), and a `+"`403`"+` error occurs in a browser due to Origin / CORS. + +## Origin-based security + +When a request is sent from a browser, HTTP RPC API follows the [Origin-based security model](https://en.wikipedia.org/wiki/Same-origin_policy), and expects the `+"`Origin`"+` HTTP header to be present. +The API will return HTTP Error 403 when Origin is missing, does not match the API port, or is not safelisted via `+"`API.HTTPHeaders.Access-Control-Allow-Origin`"+` in the config. -## HTTP commands +## HTTP RPC commands `, time.Now().Format("2006-01-02"), IPFSVersion(),