Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: document RPC + Origin-based security #959

Merged
merged 2 commits into from
Jan 24, 2022
Merged

feat: document RPC + Origin-based security #959

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4723ad6
feat: document RPC + Origin-based security
lidel Dec 3, 2021
a7bb846
Merge branch 'main' into feat/rpc-api-origin
johnnymatthews Dec 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions tools/http-api-docs/markdown.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

<!-- DO NOT EDIT THIS FILE. This file is auto-generated. Any changes you make to this file will be overwritten. To edit this file, change the contents of the https://github.com/ipfs/ipfs-docs/blob/main/tools/http-api-docs/markdown.go template. -->

_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.
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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(),
Expand Down