Tagged Data

From ArdorDocs
Jump to: navigation, search

Tagged data are similar to prunable plain messages without a recipient, but with additional searchable metadata fields.

Detect Mime Type

Gets the mime type of uploaded file or data. Javadoc

Request:

  • requestType is detectMimeType
  • data is the data (optional)
  • file is the pathname of a data file to upload (optional if data provided)
  • filename is a filename to associate with data (optional if file uploaded in which case the uploaded filename is always used)
  • isText is false if data is a hex string (optional)

Response

  • type (S) is the mime type
  • requestProcessingTime (N) is the API request processing time (in millisec)

Detect Mime Type Example

http://localhost:27876/nxt?
  requestType=detectMimeType&
  data=/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRo...&
  isText=false
{
 "requestProcessingTime": 348,
 "type": "image/png"
}


Download Tagged Data

Download tagged data as a file if it is still available. Javadoc

Request:

  • requestType is downloadTaggedData
  • chain the chain related to the operation
  • transaction is the transaction ID of the tagged data
  • retrieve is true to retrieve pruned data from other nodes if not available (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response: The downloaded data file named ardor, unless there is an error in the request.

Download Tagged Data Example

http://localhost:27876/nxt?
  requestType=downloadTaggedData&
  chain=2&
  transaction=9169681701986886056
Downloaded file named ''ardor'' with contents:
d4f167249340d6d746f49441b8ccdb1bd3521feb


Get Account Tagged Data

Get all available tagged data uploaded by a given account in reverse chronological order. Javadoc

Request:

  • requestType is getAccountTaggedData
  • chain the chain related to the operation
  • account is the account ID
  • firstIndex is a zero-based index to the first tagged data to retrieve (optional)
  • lastIndex is a zero-based index to the last tagged data to retrieve (optional)
  • includeData is true to include data (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • data (A) is an array of tagged data objects (refer to Get Tagged Data with hash omitted for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Account Tagged Data Example

http://localhost:27876/nxt?
  requestType=getAccountTaggedData&
  chain=2&
  account=ARDOR-4VDY-LNVT-LMAY-FMCKA&
  lastIndex=0
{
 "data": [
  {
   "data": "d4f167249340d6d746f49441b8ccdb1bd3521feb",
   "channel": "torrent",
   "description": "Hash of the torrent.",
   "type": "",
   "parsedTags": [
    "video",
    "scifi",
    "torrent"
   ],
   "transactionTimestamp": 47843875,
   "tags": "video, scifi, torrent",
   "filename": "",
   "accountRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
   "name": "Stargate SG1 full series",
   "blockTimestamp": 47672045,
   "transaction": "9086193976300572942",
   "account": "15295723609781267838",
   "isText": true
  }
 ],
 "requestProcessingTime": 2
}


Get All Tagged Data

Get all available tagged data in reverse chronological order. Javadoc

Request:

  • requestType is getAllTaggedData
  • chain the chain related to the operation
  • includeData is true to include data (optional)
  • firstIndex is a zero-based index to the first tagged data to retrieve (optional)
  • lastIndex is a zero-based index to the last tagged data to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • data (A) is an array of tagged data objects (refer to Get Tagged Data with hash omitted for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get All Tagged Data Example

http://localhost:27876/nxt?
  requestType=getAllTaggedData&
  chain=2&
  lastIndex=0
{
 "requestProcessingTime": 1,
 "data": [
  {
   "data": "d4f167249340d6d746f49441b8ccdb1bd3521feb",
   "channel": "torrent",
   "description": "Hash of the torrent.",
   "type": "",
   "parsedTags": [
    "video",
    "scifi",
    "torrent"
   ],
   "transactionTimestamp": 47843875,
   "tags": "video, scifi, torrent",
   "filename": "",
   "accountRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
   "name": "Stargate SG1 full series",
   "blockTimestamp": 47672045,
   "transaction": "9086193976300572942",
   "account": "15295723609781267838",
   "isText": true
  }
 ]
}


Get Channel Tagged Data

Get available tagged data by channel, optionally filtered by account, in reverse chronological order. Javadoc

Request:

  • requestType is getChannelTaggedData
  • chain the chain related to the operation
  • channel is the channel string
  • account is an account ID (optional)
  • includeData is true to include data (optional)
  • firstIndex is a zero-based index to the first tagged data to retrieve (optional)
  • lastIndex is a zero-based index to the last tagged data to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • data (A) is an array of tagged data objects (refer to Get Tagged Data with hash omitted for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Channel Tagged Data Example

http://localhost:27876/nxt?
  requestType=getChannelTaggedData&
  chain=2&
  channel=video&
  lastIndex=0
{
 "data": [
  {
   "data": "d4f167249340d6d746f49441b8ccdb1bd3521feb",
   "channel": "video",
   "description": "Hash of the video.",
   "type": "",
   "parsedTags": [
    "video",
    "scifi",
    "torrent"
   ],
   "transactionTimestamp": 47843875,
   "tags": "video, scifi, torrent",
   "filename": "",
   "accountRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
   "name": "Stargate SG1 full series",
   "blockTimestamp": 47672045,
   "transaction": "9086193976300572942",
   "account": "15295723609781267838",
   "isText": true
  }
 ],
 "requestProcessingTime": 1
}


Get Data Tag Count

Get the total number of distinct available data tags. Javadoc

Request:

  • requestType is getDataTagCount
  • chain the chain related to the operation
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • numberOfDataTags (N) is the total number of distinct data tags
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Data Tag Count Example

http://localhost:27876/nxt?
  requestType=getDataTagCount&
  chain=2
{
 "numberOfDataTags": 36,
 "requestProcessingTime": 2
}


Get Data Tags

Get the distinct tags of all available tagged data, with the number of uses of each tag, in order of number of uses, then alphabetical order. Javadoc

Request:

  • requestType is getDataTags
  • chain the chain related to the operation
  • firstIndex is a zero-based index to the first tag to retrieve (optional)
  • lastIndex is a zero-based index to the last tag to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • tags (A) is an array of tag objects including the fields:
    • tag (S) is a tag word
    • count (N) is the number of uses of tag among all tagged data
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Data Tags Example

http://localhost:27876/nxt?
  requestType=getDataTags&
  chain=2
{
 "requestProcessingTime": 5,
 "tags": [
  {
   "count": 2,
   "tag": "video"
  },
  {
   "count": 1,
   "tag": "scifi"
  },
  {
   "count": 1,
   "tag": "torrent"
  }
 ]
}


Get Data Tags Like

Prefix search of available data tags, return in alphabetical order. Javadoc

Request:

  • requestType is getDataTagsLike
  • chain the chain related to the operation
  • tagPrefix is the prefix to search for (2 character minimum) among all data tags
  • firstIndex is a zero-based index to the first tag to retrieve (optional)
  • lastIndex is a zero-based index to the last tag to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • tags (A) is an array of tag objects including the fields:
    • tag (S) is a tag word
    • count (N) is the number of uses of tag among all tagged data
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Data Tags Like Example

http://localhost:27876/nxt?
  requestType=getDataTagsLike&
  chain=2&
  tagPrefix=con
{
 "requestProcessingTime": 2,
 "tags": [
  {
   "count": 3,
   "tag": "contract"
  },
  {
   "count": 1,
   "tag": "contracts"
  }
 ]
}


Get Tagged Data

Get available tagged data given a transaction ID. Javadoc

Request:

  • requestType is getTaggedData
  • chain the chain related to the operation
  • transactionFullHash is the transaction Full Hash
  • includeData is true to include data (optional)
  • retrieve is true to retrieve pruned data from other nodes if not available (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • data (S) is the tagged data
  • channel (S) is the metadata channel field
  • description (S) is the metadata description field
  • transactionFullHash (S) is the is the transaction Full Hash of the tagged data
  • type (S) is the metadata type field
  • parsedTags (A) is an array of tag words (S) parsed from tags
  • filename (S) is the metadata filename field
  • transactionTimestamp (N) is the transaction timestamp (in seconds since the genesis block)
  • tags (S) is the metadata tags field
  • accountRS (S) is the Reed-Solomon address of the uploading account
  • name (S) is the metadata name field
  • isText (B) is the metadata isText field
  • account (S) is the number of the account that originally uploaded the tagged data
  • transaction (S) is the transaction ID
  • blockTimestamp (N) is the block timestamp (in seconds since the genesis block)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Note: Refer to Upload Tagged Data for details about the data and metadata (filename, name, description, tags, type, channel and isText) fields.

Get Tagged Data Example

http://localhost:27876/nxt?
  requestType=getTaggedData&
  transaction=9086193976300572942
{
 "data": "public note!!",
 "channel": "xxx.codebasehq.com",
 "description": "https://xxx.codebasehq.com/projects/xcubicle-store-office/tickets/8954",
 "transactionFullHash": "5ccfd5bb0a6a0e2114eac09fd5f65ba838d7e7af53b025f173a74573a28395af",
 "requestProcessingTime": 0,
 "type": "text/plain",
 "parsedTags": [
  "note"
 ],
 "transactionTimestamp": 21364804,
 "tags": "note",
 "filename": "",
 "accountRS": "ARDOR-VD7H-CE5D-A7A2-APTAS",
 "name": "jd13VOeBIQXjq9FFQthFKwCKZN3AUCs8qWRj916U6GQ_",
 "blockTimestamp": 21364835,
 "account": "10097973420206435503",
 "isText": true
}


Search Tagged Data

Full text search on available tagged data name, description and tags; optionally filtered by tag, channel or uploading account; return in reverse relevance order. Javadoc

Request:

  • requestType is searchTaggedData
  • chain the chain related to the operation
  • query is a full text query on the metadata fields name (S), description (S) and tags (S) in the standard Lucene syntax
  • tag is a word in the tags string (optional)
  • channel is a channel string (optional)
  • account is an account ID (optional)
  • includeData is true to include data (optional)
  • adminPassword Admin password parameter (optional)
  • firstIndex is a zero-based index to the first tagged data to retrieve (optional)
  • lastIndex is a zero-based index to the last tagged data to retrieve (optional)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • data (A) is an array of tagged data objects (refer to Get Tagged Data with hash omitted for details)
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Search Tagged Data Example

http://localhost:27876/nxt?
  requestType=searchTaggedData&
  chain=2&
  query=SG?&
  lastIndex=0
{
 "data": [
  {
   "data": "d4f167249340d6d746f49441b8ccdb1bd3521feb",
   "channel": "torrent",
   "description": "Hash of the torrent.",
   "type": "",
   "parsedTags": [
    "video",
    "scifi",
    "torrent"
   ],
   "transactionTimestamp": 47843875,
   "tags": "video, scifi, torrent",
   "filename": "",
   "accountRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
   "name": "Stargate SG1 full series",
   "blockTimestamp": 47672045,
   "transaction": "9086193976300572942",
   "account": "15295723609781267838",
   "isText": true
  }
 ],
 "requestProcessingTime": 22
}


Upload Tagged Data

Upload and broadcast new tagged data. POST only. Javadoc

Request: Refer to Create Transaction Request for common parameters.

  • requestType is uploadTaggedData
  • chain the chain related to the operation
  • name is the name or title of data (optional if file uploaded in which case the uploaded filename is used, but name takes precedence if provided)
  • description is a description of data (optional)
  • tags is a list of up to 5 words from 3 to 20 characters long and separated by spaces and/or commas, describing the actual content of data; for example: audio,mp3,classical (optional)
  • type is the mime type of data such as torrent, pdf, doc, image, etc. (optional)
  • channel is a data feed label such as contracts, wikileaks, etc. (optional)
  • isText is false if data is a hex string (optional)
  • filename is a filename to associate with data (optional if file uploaded in which case the uploaded filename is always used)
  • data is the data (optional)
  • file is the pathname of a data file to upload (optional if data provided)

Note: The maximum length of data plus all associated metadata is 42 kilobytes. The maximum length of description is 1000 bytes. The maximum length of the other metadata (name, tags, type, channel and filename) is 100 bytes each.

Response: Refer to Create Transaction Response.

Upload Tagged Data Example

http://localhost:27876/nxt?
  requestType=uploadTaggedData&
  chain=2&
  data=d4f167249340d6d746f49441b8ccdb1bd3521feb&
  name=Stargate SG1 full series&
  description=Hash of the torrent.&
  tags=video, scifi, torrent&
  channel=torrent&
  secretPhrase=secretPhrase&
  feeNQT=100000000&
  deadline=60
{
 "minimumFeeFQT": "34000000",
 "signatureHash": "953a1023c84939a6e31da0db913ed2829b318d59663daddce63bdf2193af912e",
 "transactionJSON": {
  "senderPublicKey": "10f09c34f225d425306e5be55a4946908156072afbead4d574a512d7e086ef5c",
  "chain": 2,
  "signature": "17da947a7dc30a6d722a53f064d817c559f8f9c1387290048793d81b49dbf5082a0...",
  "feeNQT": "100000000",
  "type": 6,
  "fullHash": "0e91b0dd47a5187e26ea5b54f1917e3b879ee3cf096eb597ce22c6833863cdb2",
  "version": 1,
  "fxtTransaction": "0",
  "phased": false,
  "ecBlockId": "7868019187120003959",
  "signatureHash": "953a1023c84939a6e31da0db913ed2829b318d59663daddce63bdf2193af912e",
  "attachment": {
   "filename": "",
   "data": "d4f167249340d6d746f49441b8ccdb1bd3521feb",
   "name": "Stargate SG1 full series",
   "channel": "torrent",
   "description": "Hash of the torrent.",
   "type": "",
   "version.TaggedDataUpload": 1,
   "isText": true,
   "hash": "06fbac5b5358c00f5a2f19789b06220dca4e242a851b70072633a06ae8e6fb46",
   "tags": "video, scifi, torrent"
  },
  "senderRS": "ARDOR-4VDY-LNVT-LMAY-FMCKA",
  "subtype": 0,
  "amountNQT": "0",
  "sender": "15295723609781267838",
  "ecBlockHeight": 304598,
  "deadline": 60,
  "transaction": "9086193976300572942",
  "timestamp": 47671075,
  "height": 2147483647
 },
 "unsignedTransactionBytes": "06102367d7023c0010f09c34f225d425306e5be55a494...",
 "broadcasted": true,
 "requestProcessingTime": 284,
 "transactionBytes": "06102367d7023c0010f09c34f225d425306e5be55a49469081560...",
 "fullHash": "0e91b0dd47a5187e26ea5b54f1917e3b879ee3cf096eb597ce22c6833863cdb2",
 "bundlerRateNQTPerFXT": "10000000"
}


Verify Tagged Data

Verify expired tagged data downloaded from another node, against the hash in the blockchain. Javadoc

Request:

  • requestType is verifyTaggedData
  • chain the chain related to the operation
  • transactionFullHash is the transaction Full Hash
  • data is the tagged data (optional)
  • file s the pathname of a data file to upload (optional if data provided)
  • filename (S) is the metadata filename field
  • name (S) is the metadata name field
  • description (S) is the metadata description field
  • tag is a word in the tags string (optional)
  • type is the mime type of data such as torrent, pdf, doc, image, etc. (optional)
  • channel is a channel string (optional)
  • isText (B) is the metadata isText field
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: The data and metadata (filename, name, description, tags, type, channel and isText) must have exactly the same values as when the data was uploaded (refer to Upload Tagged Data).

Response:

  • verify (B) is true if the hash of the provided data and metadata matches the hash in the blockchain
  • hash (S) is the hash of the tagged data
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)
  • version.TaggedDataUpload (N) is 1, the version number

Note: This call returns an error if there is a hash mismatch.

Verify Tagged Data Example

http://localhost:27876/nxt?
  requestType=verifyTaggedData&
  chain=2&
  transactionFullHash=95abb707e526cd14d01e5c41f62effa78a90a7b3887e1c5521309a7698ea4af7&
  data=d4f167249340d6d746f49441b8ccdb1bd3521feb&
  name=Stargate SG1 full series&
  description=Hash of the torrent.&
  tags=video, scifi, torrent&
  channel=torrent
{
 "verify": true,
 "requestProcessingTime": 7,
 "version.TaggedDataUpload": 1,
 "hash": "06fbac5b5358c00f5a2f19789b06220dca4e242a851b70072633a06ae8e6fb46"
}