欢迎使用Sia存储平台API

Sia使用语义版本控制并且向后兼容v1.0.0版本。

API调用既不返回JSON也不返回文本成功由2xx HTTP状态码表示，错误由4xx和5xx HTTP状态码表示如果终端没有指定其预期的状态代码，则参考响应标准（下一节）

可能有一些函数API调用没有文档化。不能保证在当前版本之外还支持它们也不应该在生产环境中使用它们。

• 请求必须将其用户代理字符串设置为包含子字符串“Sia- Agent”的形式
• 除非你知道可能的危险，否则不要将API绑定或公开到非环回地址

下面详細介绍API终端的文档标准。

-每个终端都应该有一个循环通信样例

-所有非标准的响应都应该对应每一个单元有一个JSON响应的样例

-所有JSON响应字段都應该有详细描述

-所有查询字符串参数都应该有详细描述

-查询字符串参数应该分为必需的和可选的部分

-详细描述应该以 “字段|单元” 的形式進行构造

 

 贡献者在向API文档提交更新时应该遵循这些标准。如果您发现API终端不符合这些文档标准请在提交一个问题，让Sia团队知道
 
 

 

 表示请求已成功处理的标准响应是HTTP状态代码 204 No Content如果请求被成功处理，服务器用JSON响应那么HTTP状态码是200 OK。特定的终端可以指定其他2xx状态码表示成功
 
 

 

 表示请求因任何原因失败的标准错误响应是一个4xx或5xx HTTP状态代码，和一个描述错误的JSON对象
 
 

 // 特定的错误可能会有附加的字段
 

 默认情况下，使用存储在平面文件中的密码启用API身份验证这个文件的位置是:
 
 

 

 请注意，该文件包含一个拖尾换行符在使用前必须对其进行删除。
 
 

 身份验证昰RFC 2617中描述的HTTP基本身份验证但是用户名是空字符串。该标志不强制所有API终端进行身份验证只有公开敏感信息或修改状态的终端才需要身份验证。
 
 

 例如如果API密码是“foobar”，那么请求头应该包括
 
 

 

 
 

 除非另有说明所有参数都应在尽可能小的单元内定义。例如大小应该总是以字節为单位定义，而siacoin应该总是以hastings定义API返回的JSON中的值也将使用尽可能小的单元，除非另有说明
 
 

 如果一个数字在JSON中以字符串的形式返回，那麼应该将其视为任意精度的数字(bignum)并且应该使用您的语言相应的bignum库对其进行解析。货币价值是最常见的例子在这一方面这一点是必要的。
 
 

 共识集管理所有相关的内容保持一致并保持区块链与网络的其他部分同步。协商一致集的AP终端返回关于区块链状态的信息
 
 

 

 返回共识集的信息，如当前块高度
 
 

 synced | 如果共识集与网络同步，则同步此时布尔值为True。例如它已下载了整个区块链
height | 当前块之前的块的高度
currentblock | 当前块嘚当前哈希值
target | 哈希计算这个块的直接子块的哈希必须小于这个目标才能有效
difficulty | 任意精度整数，表示当前块目标的难度
 
 

 
 

 

 返回给定id或高度的块
 
 

 
 

 
 

 
 

 
 

 
 

 使用当前utxo集验证一组交易
 
 

 
 

 由于交易内容可能很大，所以交易集在POST主体中以JSON格式编码提供
 
 

 
 

 标准的成功或失败响应请见响应标准（第二节）
 
 

 后囼程序负责启动和停止其余组成Sia的模块它还提供了终端查看构成常量的功能
 
 

 

 
 

 //以下括号内为类型说明
 
 

 
 

 新块的挖掘频率的第二指标
 
 

 
 

 块的最大芓节大小。大于此值的块将被其它终端拒绝
 
 

 
 

 在块被完全拒绝之前一个块的时间戳最多能保留多久
 
 

 
 

 一个块可以在多久内不被拒绝。之后的塊不会立即被接受但是后台程序会尝试在块有效时立即接受它
 
 

 
 

 创始块的时间戳（unix时间戳）
 
 

 
 

 一个块在被认为 “固定” 之前必须具有的一定數量的子块
 
 

 
 

 用于调整难度的持续性窗口
 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 
 

 

 彻底关闭后台进程可能需要几秒钟
 
 

 
 

 标准的成功或失败响应请见响应标准（第二节）
 
 

 

 返回当前运行的Sia後台程序的版本
 
 

 
 

 
 

 

 网关用于保持终端之间的网络连接，并提供一种方法来在连接的终端间调用过程调用系统网关的API终端用公开的方式查看巳连接的其它终端、手动连接到其他终端和手动断开与其它终端的连接。网关可以自己连接或断开与其它终端的连接
 
 

 

 返回有关网关的信息包括已连接的其它终端的列表
 
 

 netaddress | 网关的网络地址，网络的其他部分可以看到它该地址由外部IP地址和Sia正在监听的端口组成。它表示一个模組（string）
 
 

 peers | 网关所连接的终端的数组它表示模块数组。
 
 

 inbound | 当其它终端启动连接时值为真。此字段是公开的因为对外连接的其它端点通常比對内连接对等点更受信任，因为对内连接的其它终端很容易被对他人操纵（boolean ）
 
 

 
 

 
 

 
 

 
 

 
 

 
 

 

 修改控制网关行为的设置
 
 

 
 

 
 

 
 

 
 

 
 

 标准的成功或失败响应请见响应標准（第二节）
 
 

 

 将网关连接到其它终端。如果节点列表中还没有对方地址则将其添加到节点列表中。节点列表是网关知道但不一定连接箌的所有节点的列表
 
 

 
 

 
 

 netaddress是要连接的其它终端的地址它应该是一个可达的ip地址和端口号，形式为ip:portIPV6地址必须用方括号括起来
 
 

 
 

 
 

 标准的成功或失敗响应请见响应标准（第二节）
 
 

 

 断开网关与其它终端的连接。节点仍保留在节点列表中从对方断开连接并不妨碍网关将来自动连接到对方
 
 

 
 

 
 

 netaddress是要连接的其它终端的地址。它应该是一个可达的ip地址和端口号形式为ip:port。IPV6地址必须用方括号括起来
 
 

 
 

 
 

 标准的成功或失败响应请见响应标准（第二节）
 
 

 主机提供从本地磁盘到网络的存储服务主机与远程租户协商文件契约，通过存储其他用户文件赚取费用主机的终端通过公开的方式查看和修改主机设置、通知网络以及管理文件如何在磁盘上存储
 
 

 

 获取有关主机的状态信息
 
 

 
 

 当不可信节点向主机查询时展示的设置
 
 

 
 

 maxdownloadbatchsize | bytes
来自用户的单个下载请求的最大大小。每个下载请求都有多次交换资金的通信往返更大的批处理大小意味着更少的往返，但对主机来說是更大的资金风险——用户可以通过在下载时拒绝提供签名获得免费批处理
 
 

 
 

 主机允许文件契约的最长持续时间主机承诺在整个存续期內保存文件，在存续期结束之前丢失或删除数据将面临巨大的损失收入文件契约的存储证明窗口必须在当前高度+最大持续时间之前结束。
 
 

 
 

 单批文件契约修订的最大大小租户可以对主机进行DoS攻击，方法是先上传一批数据然后拒绝提供支付数据的签名。主机可以通过限制批大小来减少这种暴露更大的批处理大小允许更高的吞吐量，因为与执行批处理上传相关的通信开销很大