From 68590e2ac99a03e5fc145c858b76e92d222e4b44 Mon Sep 17 00:00:00 2001 From: sig Date: Thu, 24 Jun 2021 14:09:07 +0100 Subject: [PATCH] update api specs --- static/api/index.html | 68 +++++++++++++++++++++---------------- static/debug-api/index.html | 39 ++++++++++++++------- 2 files changed, 65 insertions(+), 42 deletions(-) diff --git a/static/api/index.html b/static/api/index.html index 715d158ba..8a4f9a73e 100644 --- a/static/api/index.html +++ b/static/api/index.html @@ -553,7 +553,7 @@ -
Documentation Powered by ReDoc
Documentation Powered by ReDoc
swarm-postage-batch-id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get referenced data

Authorizations:
path Parameters
required
string or string or string

Swarm address reference to content

+

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get referenced data

Authorizations:
path Parameters
required
string or string or string

Swarm address reference to content

Responses

Response samples

Content type
application/problem+json
"string"

Chunk

Get Chunk

Authorizations:
path Parameters
required
string or string or string

Swarm address of chunk

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Chunk

Get Chunk

Authorizations:
path Parameters
required
string or string or string

Swarm address of chunk

query Parameters
targets
string

Global pinning targets prefix

Responses

Response samples

Content type
application/problem+json
"string"

Upload Chunk

Authorizations:
header Parameters
swarm-tag
integer

Associate upload with an existing Tag UID

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Upload Chunk

Authorizations:
header Parameters
swarm-tag
integer

Associate upload with an existing Tag UID

swarm-pin
boolean

Represents the pinning state of the chunk

swarm-postage-batch-id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

File

Upload file or a collection of files

In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.

+

Response samples

Content type
application/json
{
  • "status": "string"
}

File

Upload file or a collection of files

In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.

User can also upload a tar file along with the swarm-collection header. This will upload the tar file after extracting the entire directory structure.

If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads.

A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files uploaded as a multipart request, the swarm-index-document header should be used with the name of the file.

@@ -615,10 +617,11 @@
swarm-postage-batch-id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Request Body schema:
multipart/form-data
multipart/form-data
application/octet-stream
application/x-tar
file
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Collection

Upload file or a collection of files

In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.

+

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Collection

Upload file or a collection of files

In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.

User can also upload a tar file along with the swarm-collection header. This will upload the tar file after extracting the entire directory structure.

If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads.

A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files uploaded as a multipart request, the swarm-index-document header should be used with the name of the file.

@@ -633,17 +636,18 @@
swarm-postage-batch-id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Request Body schema:
multipart/form-data
multipart/form-data
application/octet-stream
application/x-tar
file
Array of strings <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get file or index document from a collection of files

Authorizations:
path Parameters
required
string or string or string

Swarm address of content

+

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get file or index document from a collection of files

Authorizations:
path Parameters
required
string or string or string

Swarm address of content

query Parameters
targets
string

Global pinning targets prefix

Responses

Response samples

Content type
application/problem+json
"string"

Get referenced file from a collection of files

Authorizations:
path Parameters
required
string or string or string

Swarm address of content

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Get referenced file from a collection of files

Authorizations:
path Parameters
required
string or string or string

Swarm address of content

path
required
string

Path to the file in the collection.

query Parameters
targets
string

Global pinning targets prefix

Responses

Response samples

Content type
application/problem+json
"string"

Reupload file

Reupload a root hash to the network

Authorizations:
path Parameters
required
string or string or string

Root hash of content

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Reupload file

Reupload a root hash to the network

Authorizations:
path Parameters
required
string or string or string

Root hash of content

Responses

Response samples

Content type
application/problem+json
"string"

Reupload collection

Reupload a root hash to the network

Authorizations:
path Parameters
required
string or string or string

Root hash of content

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Reupload collection

Reupload a root hash to the network

Authorizations:
path Parameters
required
string or string or string

Root hash of content

Responses

Response samples

Content type
application/problem+json
"string"

Tag

Get list of tags

Authorizations:
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Tag

Get list of tags

Authorizations:
query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

Responses

Response samples

Content type
application/json
{
  • "tags":
    [
    ]
}

Create Tag

Authorizations:
Request Body schema: application/json
address
string ^[A-Fa-f0-9]{64}$

Responses

Response samples

Content type
application/json
{
  • "tags":
    [
    ]
}

Create Tag

Authorizations:
Request Body schema: application/json
address
string ^[A-Fa-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "total": 0,
  • "processed": 0,
  • "synced": 0
}

Get Tag information using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

+

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "total": 0,
  • "processed": 0,
  • "synced": 0
}

Get Tag information using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

Responses

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "total": 0,
  • "processed": 0,
  • "synced": 0
}

Delete Tag information using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

+

Response samples

Content type
application/json
{
  • "uid": 0,
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "total": 0,
  • "processed": 0,
  • "synced": 0
}

Delete Tag information using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

Responses

Response samples

Content type
application/problem+json
"string"

Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid

Authorizations:
path Parameters
uid
required
integer

Uid

Request Body schema: application/json

Can contain swarm hash to use for the tag

address
string ^[A-Fa-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Root hash pinning

Pin the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

-

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "status": "string"
}

Root hash pinning

Pin the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Unpin the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

+

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Unpin the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Get pinning status of the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

+

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Get pinning status of the root hash with the given reference

Authorizations:
path Parameters
required
string or string

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
"36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2"

Get the list of pinned root hash references

Authorizations:

Responses

Response samples

Content type
application/json
"36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2"

Get the list of pinned root hash references

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "addresses":
    [
    ]
}

Postal Service for Swarm

Send to recipient or target with Postal Service for Swarm

Authorizations:
path Parameters
topic
required
string

Topic name

+

Response samples

Content type
application/json
{
  • "addresses":
    [
    ]
}

Postal Service for Swarm

Send to recipient or target with Postal Service for Swarm

Authorizations:
path Parameters
topic
required
string

Topic name

targets
required
string

Target message address prefix. If multiple targets are specified, only one would be matched.

query Parameters
recipient
string

Recipient publickey

header Parameters
swarm-postage-batch-id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Responses

Response samples

Content type
application/problem+json
"string"

Subscribe for messages on the given topic.

Authorizations:
path Parameters
topic
required
string

Topic name

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Subscribe for messages on the given topic.

Authorizations:
path Parameters
topic
required
string

Topic name

Responses

Response samples

Content type
application/problem+json
"string"

Single owner chunk

Upload single owner chunk

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

+

Response samples

Content type
application/problem+json
{
  • "message": "string",
  • "code": 0
}

Single owner chunk

Upload single owner chunk

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

id
required
string ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Id

query Parameters
sig
required
string ^([A-Fa-f0-9]+)$
Example: sig=cf880b8eeac5093fa27b0825906c600685

Signature

header Parameters
swarm-pin
boolean

Represents the pinning state of the chunk

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Feed

Create an initial feed root manifest

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

+

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Feed

Create an initial feed root manifest

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

topic
required
string ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic

query Parameters
type
string ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

header Parameters
swarm-pin
boolean

Represents the pinning state of the chunk

@@ -743,9 +750,10 @@

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Find feed update

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

+

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Find feed update

Authorizations:
path Parameters
owner
required
string ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Owner

topic
required
string ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic

query Parameters
at
integer

Timestamp of the update (default: now)

type
string ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

@@ -754,13 +762,13 @@

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Postage Stamps

Get all available stamps for this node

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Postage Stamps

Get all available stamps for this node

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "stamps":
    [
    ]
}

Get an individual postage batch status

Authorizations:
path Parameters
id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

+

Response samples

Content type
application/json
{
  • "stamps":
    [
    ]
}

Get an individual postage batch status

Authorizations:
path Parameters
id
required
string ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "utilization": 0
}

Buy a new postage batch. \n\n Be aware, this endpoint create an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!

Authorizations:
path Parameters
amount
required
integer

Amount of BZZ added that the postage batch will have.

+

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "utilization": 0,
  • "usable": true,
  • "label": "string",
  • "depth": 0,
  • "amount": "1000000000000000000",
  • "bucketDepth": 0,
  • "blockNumber": 0,
  • "immutableFlag": true
}

Buy a new postage batch. Be aware, this endpoint create an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!

Authorizations:
path Parameters
amount
required
integer

Amount of BZZ added that the postage batch will have.

depth
required
integer

Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16)

query Parameters
label
string

An optional label for this batch

header Parameters
gas-price
integer

Gas price for transaction

@@ -768,9 +776,9 @@

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}
+

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}