Payswarm - Web API

Abstract

This document defines a set of REST Web APIs to enable the legal transfer of commercialized digital content. These APIs enable new Web-based business models by specifying methods of interaction between user agents and web servers to exchange digital goods and ensure the subequent distribution of monetary compensation to the content distributors and rights holders.

6. The Purchase Process

This section describes the media discovery, license acquisition, contract drafting, negotiating, data transfer, payment and file assembly process in detail.

6.1 Media Discovery

Buyer finds the Media they want to purchase.
- Media can be found on a digital content sales website encoded in RDFa, in a file recognized by the browser as a media description, or anywhere else on the web.
- Digitally signed media could be found, in the future, by multicast (or other broadcast-like method) via peers on the network.

6.2 License Selection

Current implementation includes license information in the Media object. Future implementations may split these two apart.
PaySwarm Authority must digitally sign the Media so the Buyer can purchase it later. Sellers may also elect to reject negotiation attempts with them if the associated Media is not already signed.

6.3 Asserting Purchase Preferences

Buyer selects from the available options their preferred media file format, number of sellers, particular sellers, type of purchase (PeerBuy vs. WebBuy), etc.
May include purchase amount, minimum download rate, guaranteed streaming rate, and account ID but doesn't need to. This can be specified at the time of purchase.

6.4 Creating a Ware Bundle

The media and files to be purchased are added to a WareBundle.

6.5 Brokering a Non-Swarming Contract

Note: Used primarily for non-PaySwarming-aware Web browser based purchases (for old browsers).
Website sends the Contract to the Broker, which broker's a contract on behalf of the Buyer.
The Broker handles negotiating with 1 Seller, which is usually the Website.

6.6 Brokering a Swarming Contract

A WareBundle is constructed by the Buyer, using the Media and PurchasePreferences extracted from RDFa or other semantic markup on the page, or auto-generated by the User Agent.
A number of Sellers are selected by the Buyer based on the PurchasePreferences.

6.7 Negotiating with a Seller

Note: A Broker may act on behalf of a Buyer.
Buyer creates a ContractSection with favorable or default terms.
Buyer sends the Contract with the single ContractSection to the Seller.
ContractSection contains a Ware that the Seller is expected to be selling.
- In the case of a ware bundle in PeerBuy, multiple wares may be constructed from the bundle, if for instance it contained an audio album with X songs. Each song would be negotiated for separately, but would include the License from the album.
Seller receives the Contract which includes the negotiated ContractSection.
Seller optionally checks the Contract's Media License for the PaySwarm Authority's digital signature.
- If the signature fails, the Seller may simply deny the negotiation request. The seller may also allow it to proceed if they trust the buyer enough to assume the buyer will get a signature later and will not have wasted the seller's bandwidth for downloading an encrypted piece.
Seller adjusts the ContractSection according to their terms.
- EDITORS NOTE: Add details about signing algorithm, explain how cheating is avoided by signing particular fields.
Seller digitally signs the ContractSection establishing non-repudiation and implicitly agreeing to any terms they set forth.
For Swarm-based purchases, Seller adds the signature, their profile ID, and a SwarmingPurchaseKey to the ContractSection that the buyer uses to authorize downloading FilePieces from the Seller.
Seller returns the updated Contract w/ContractSection.
If the buyer agrees to the Seller's terms, they will also sign the ContractSection.

6.8 Downloading a FilePiece

Buyer's sends, to the Seller, the ContractSection hash, the file ID, the media ID, the index of the FilePiece, the standard FilePiece size, the peerbuyKey, the ID of the Profile the Seller used to sign the ContractSection, and the ID of the Binary File Processor the Seller must use.
Seller ensures the ContractSection hash and SwarmingPurchaseKey are valid.
Seller loads the appropriate Binary File Processor.
Seller begins streaming the FilePiece through the Binary File Processor to the Buyer.
Binary File Processor generates a unique PieceKey and OpenKey.
- The PieceKey is used to encrypt the FilePiece data.
- The OpenKey is used to encrypt the PieceKey.
  - The OpenKey is itself encrypted with a PublicKey unique to the Seller, whose PrivateKey pair is stored on the PaySwarm Authority.
  - Only the PaySwarm Authority can unlock the OpenKey, which in turn, means only the PaySwarm Authority can unlock the PieceKey.
  - FIXME: It seems this could be optimized to just locking the PieceKey with the PublicKey... and perhaps wasn't done this way due to some limitation with OpenSSL's API.
Binary File Processor signs FilePiece information.
Seller sends actual FilePiece size, the Binary File Processor's signature on the FilePiece, the Seller's profile ID and signature on the FilePiece, the encrypted PieceKey, and the encrypted OpenKey to the Buyer.
- EDITORS NOTE: Add details about what is signed on a FilePiece and why, explain how cheating is avoided by signing particular fields

6.9 Purchasing the License

Buyer sends the Contract with the Media License to the PaySwarm Authority.
PaySwarm Authority checks the signature on the Media License.
PaySwarm Authority moves money from the Buyer's account to the accounts specified in the License.

6.10 Purchasing the Data

Buyer sends a ContractSection with N FilePieces to the PaySwarm Authority.
The PaySwarm Authority verifies the Seller and Buyer signatures on the ContractSection and the Seller and Binary File Processor signatures on the FilePieces.
The PaySwarm Authority moves money from the Buyer's account to the accounts specified in the ContractSection.
- EDITORS NOTE: Add details on how payment amounts are determined
The PaySwarm Authority unlocks each FilePiece PieceKey.
The PaySwarm Authority returns the FilePieces with unlocked PieceKeys to the Buyer.

6.11 Assembling the Data

Buyer loads the Binary File Processor with the appropriate ID.
Buyer streams the encrypted FilePieces with unlocked PieceKeys through the Binary File Processor.
Binary File Processor outputs assembled file(s).
EDITORS NOTE: Add details on Binary File Processor checking/reporting bad sellers (sellers that failed to use Binary File Processors correctly)

8. API Reference

This section contains all of the developer documentation for interacting with a PaySwarm network via a standard set of REST-based API calls. Programs written in Javascript Python, Ruby, C, C++, C#, Perl, and many other programming languages can be written to interact with a PaySwarm network via the following Web Services.

POST /payees/resolve

Resolves a set of given payees to the final dollar amount.

Authentication: Optional

Returns: The return value is currently not documented.

Input Validator

(
   
   (
   
      (
         licenseAmount: string
      )
      or
   
      (
         licensePayees: array
      )
   )
   and
   
   (
      licenseAmount: optional precisemoney
      piecePayees: optional 
      (
         array
         and
         each item matches
         (
            mediaId: optional integer range(0 - 4294967296)
            description: optional string
            min: optional string
            amount: optional precisemoney
            amountResolved: optional boolean
            amountType: string
            percentage: optional string
            id: integer range(1 - 4294967296)
            taxExempt: optional boolean
         )
      )
      filePieceCount: optional integer range(1 - 4294967296)
      licensePayees: optional 
      (
         array
         and
         each item matches
         (
            mediaId: optional integer range(0 - 4294967296)
            description: optional string
            min: optional string
            amount: optional precisemoney
            amountResolved: optional boolean
            amountType: string
            percentage: optional string
            id: integer range(1 - 4294967296)
            taxExempt: optional boolean
         )
      )
      dataPayees: optional 
      (
         array
         and
         each item matches
         (
            mediaId: optional integer range(0 - 0)
            description: optional string
            min: optional string
            amount: optional precisemoney
            amountResolved: optional equals false
            amountType: 
            (
            equals PAYEE_AMOUNT_TYPE_FLATFEE
               or
            equals PAYEE_AMOUNT_TYPE_PLICENSE
               or
            equals PAYEE_AMOUNT_TYPE_PCUMULATIVE
               or
            equals PAYEE_AMOUNT_TYPE_PTOTAL
            )
            percentage: optional string
            id: integer range(1 - 4294967296)
            taxExempt: optional boolean
         )
      )
   )
)

GET /catalog/server?nodeuser=A

Gets a user's server information, including their server ID, server token, and server url.

Authentication: Required

Returns: an HTTP 200 code if successful, an exception if not.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

GET /catalog/sellerpools?fileId=A&mediaIds=B

Gets all media IDs associated with the given file ID in the set of all seller pools. Typically, there will be only one.

Authentication: Required

Returns: The return value is currently not documented.

Query Parameters

fileId - the file ID to use as a filter for the returned seller pools.
mediaIds - true to return only the list of media IDs (false not presently supported).

Query Validator

(
   mediaIds: equals true
   fileId: fileid
)

GET /catalog/sellerpools/<mediaId>

Gets all seller pools for the given media ID in the given range.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

mediaId - the media ID to use when filtering the set of sellerpools to return.

GET /catalog/sellerpools/<mediaId>/<fileId>

Gets the seller pool for the given media ID and file ID.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

mediaId - the media ID to use when filtering the set of sellerpools to return.
fileId - the file ID to use when filtering the set of sellerpools to return.

GET /catalog/payees/schemes?nodeuser=A

Gets a set of payee schemes from a user's custom catalog given a set of filters.

Authentication: Required

Returns: an HTTP 200 code if successful, an exception if not.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

GET /catalog/payees/schemes/<schemeId>?nodeuser=A

Gets an existing payee scheme from a user's custom catalog.

Authentication: Required

Returns: an HTTP 200 code if successful, an exception if not.

Path Parameters

schemeId - the ID of the payee scheme to get.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

POST /catalog/payees/schemes?nodeuser=A

Creates a new payee scheme in a user's custom catalog. The message body must contain a PayeeScheme object.

Authentication: Required

Returns: an HTTP 200 code if successful, an exception if not.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   payees: datapayees
   description: 
   (
      string
      and
      more than 1 character
   )
)

POST /catalog/payees/schemes/<schemeId>?nodeuser=A

Updates an existing payee scheme in a user's custom catalog. The message body must contain an array of Payee objects.

Authentication: Required

Returns: an HTTP 200 code if successful, an exception if not.

Path Parameters

schemeId - the ID of the payee scheme to update.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   payees: datapayees
   description: 
   (
      string
      and
      more than 1 character
   )
)

DELETE /catalog/payees/schemes/<schemeId>?nodeuser=A

Deletes an existing payee scheme from a user's custom catalog.

Authentication: Required

Returns: an HTTP 201 code if successful, an exception if not. // DELETE .../payees/schemes/

Path Parameters

schemeId - the ID associated with the scheme that should be removed.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

GET /sva/contracts/sections/<contractId>/<sellerId>

Gets the contract sections for a particular seller, according to that seller's user ID and the related contract ID.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

contractId - The ID associated with the contract.
sellerId - The ID associated with the seller of each contract section.

POST /catalog/netaccess/test?nodeuser=A

Responds to a token sent to this server to determine if another entity can access it over the net. If the token matches the unique token used by this catalog, this method will return with success.

Authentication: Required

Returns: an HTTP 201 code if successful, an exception if not.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   ip: string
   token: 
   (
      string
      and
      less than 50 characters
   )
)

Retrieves a ResourceSet of Media that are related to the specified media ID in an optionally provided way.

Authentication: Optional

Returns: HTTP 200 and a ResourceSet if successful, an exception otherwise.

Path Parameters

mediaId - The ID associated with the Media, which is used as the basis of the relationship comparison.

Query Parameters

start - The starting offset into the media set.
num - The maximum number of items to return in the ResourceSet.
relationship - The relationship type to use when building the ResourceSet. Valid values are "similar".

Query Validator

(
   start: optional integer range(0 - 4294967296)
   num: optional integer range(0 - 4294967296)
   relationship: optional regex("^(similar)$")
)

GET /media?genre=A&list=B&num=C&owner=D&query=E&start=F

Retrieves a set of media resources an a ResourceSet. The contents of the media resources are modified by the content filters passed as query parameters.

Authentication: Optional

Returns: HTTP 200 code and a ResourceSet containing all of the media items if successful, an exception otherwise.

Query Parameters

num - The number of items to fetch into the resource set.
start - The starting offset in the list of all resources in the set.
query - The query string to use when searching the media set.
owner - The UserId of the owner of the media set.
genre - The GenreId of the media set to retrieve.
list - The ListId of the media set to retrieve.

Query Validator

(
   index: optional regex("^(contributors|media)$")
   list: optional integer range(1 - 4294967296)
   owner: optional integer range(1 - 4294967296)
   start: optional integer range(0 - 4294967296)
   num: optional integer range(1 - 50)
   genre: optional integer range(1 - 4294967296)
   query: optional 
   (
      string
      and
      more than 2 characters
      and
      less than 320 characters
   )
   type: optional string
)

GET /media/<mediaId>

Retrieves a single media resource by id. The contents of the media resource are modified by the content filters passed as query parameters.

Authentication: Optional

Returns: HTTP 200 and a Media object if successful, an exception otherwise.

Path Parameters

mediaId - The ID associated with the media.

POST /media

Adds or updates a single Media resource.

Authentication: Required

Returns: HTTP 200 if successful, an exception otherwise.

Query Validator

(
   id: integer range(0 - 4294967296)
)

POST /media/<mediaId>

Updates a single Media resource.

Authentication: Required

Returns: HTTP 200 if successful, an exception otherwise.

Path Parameters

mediaId - The ID associated with the Media resource.

Query Validator

(
)

DELETE /media/<mediaId>

Deletes a single Media resource.

Authentication: Required

Returns: HTTP 200 if successful, an exception otherwise.

Path Parameters

mediaId - The ID associated with the Media resource.

GET /catalog/wares/<wareId>

Populates a ware according to its ID.

Authentication: Optional

Returns: The return value is currently not documented.

Path Parameters

wareId - the ware ID associated with the ware.

POST /catalog/wares?nodeuser=A

Creates or updates an existing Ware in a user's catalog with the given ware.

Authentication: Required

Returns: HTTP 200 OK if the add was successful, an exception otherwise.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   
   (
      mediaId: integer range(1 - 4294967296)
      id: 
      (
         string
         and
         more than 1 character
      )
      description: optional string
   )
   and
   
   (
   
      (
         fileInfo: 
         (
            id: fileid
         )
      )
      or
   
      (
         fileInfos: 
         (
            array
            and
            more than 1 character
            and
            less than 1 characters
            and
            each item matches
            (
               id: fileid
            )
         )
      )
   )
   and
   
   (
   
      (
         payeeSchemeId: integer range(1 - 4294967296)
      )
      or
   
      (
         payees: datapayees
      )
   )
)

GET /catalog/wares?nodeuser=A

Populates Wares that is contained in a user's catalog based on ware IDs or file IDs.

Authentication: Optional

Returns: HTTP 200 OK and a Ware if the ware exists, an exception otherwise.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

GET /catalog/wares/<wareId>?nodeuser=A

Populates a Ware that is contained in a user's catalog.

Authentication: Optional

Returns: HTTP 200 OK and a Ware if the ware exists, an exception otherwise.

Path Parameters

wareId - the ID of the ware to populate.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

DELETE /catalog/wares/<wareId>?nodeuser=A

Deletes a Ware that is contained in a user's catalog.

Authentication: Required

Returns: HTTP 200 OK if the ware was deleted successfully, or an exception otherwise.

Path Parameters

wareId - the ID of the ware to delete.

Query Parameters

nodeuser - the user on the node that should perform the requested action on the caller's behalf.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

POST /sva/contracts/media/<mediaId>

Gets a signed media license for a particular buyer.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

mediaId - The list of payees to associate with a particular media license.

Input Validator

(
null
   or
dynamiclicensepayees
)

GET /sva/contracts/<contractId>

Gets a contract by its ID.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

contractId - The ID associated with the contract.

POST /sales/contract/filepiece

Retrieves a filepiece from the seller.

Authentication: Required

Returns: the encrypted data for the filepiece followed by trailers with signatures and encrypted key(s).

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   index: integer range(0 - 4294967296)
   peerbuyKey: 
   (
      string
      and
      more than 1 character
   )
   mediaId: integer range(1 - 4294967296)
   sellerProfileId: integer range(1 - 4294967296)
   bfpId: integer range(1 - 4294967296)
   csHash: 
   (
      string
      and
      more than 1 character
   )
   fileId: 
   (
      string
      and
      more than 1 character
   )
   size: integer range(0 - 4294967296)
)

GET /catalog/sellers/<userId>

Gets a set of sellers for the given user ID.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

userId - the user ID associated with the seller.

GET /catalog/sellers/<userId>/<serverId>

Gets a particular seller, given the seller's user ID and server ID.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

userId - the user ID associated with the seller.
serverId - the server ID associated with the seller.

POST /catalog/sellers/<userId>

Adds a new seller for the given user ID. The new server ID and token will be returned on success.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

userId - the user ID associated with the seller.

Input Validator

(
   url: 
   (
      string
      and
      more than 1 character
   )
   listingUpdateId: string
)

POST /catalog/sellers/<userId>/<serverId>

Updates an existing seller's URL.

Authentication: Required

Returns: The return value is currently not documented.

Path Parameters

userId - the user ID associated with the seller.
serverId - the server ID associated with the seller.

Input Validator

(
   url: 
   (
      string
      and
      more than 1 character
   )
)

POST /sales/contract/negotiate

Negotiates a contract section with a seller. The buyer provides a contract section with their desired terms, the seller responds with a signed contract section containing their acceptable terms.

Authentication: Required

Returns: the seller's signed contract section, which the buyer may elect to accept.

Query Validator

(
   nodeuser: integer range(1 - 4294967296)
)

Input Validator

(
   media: 
   (
      licenseAmount: precisemoney
      piecePayees: piecepayees
      publicDomain: boolean
      title: string
      ccLicenses: string
      payees: licensepayees
      signature: string
      releaseDate: regex("^[0-9]{4}-")
      buyerId: integer range(1 - 4294967296)
      signer: 
      (
         userId: integer range(1 - 4294967296)
         profileId: integer range(1 - 4294967296)
      )
      ownerId: integer range(1 - 4294967296)
      distribution: string
      payeeRules: 
      (
         array
         and
         each item matches
         (
            mediaId: integer range(0 - 4294967296)
            value: string
            type: string
         )
      )
      type: string
      id: integer range(1 - 4294967296)
   )
   version: equals "3.0"
   buyer: 
   (
      username: optional string
      userId: integer range(1 - 4294967296)
      delegateId: optional integer range(1 - 4294967296)
      profileId: integer range(1 - 4294967296)
   )
   sections: 
   (
      map
      and
      each item matcheseach item matches
      (
         negotiationTerms: optional map
         seller: 
         (
            username: optional string
            userId: integer range(1 - 4294967296)
            serverId: integer range(1 - 4294967296)
            url: string
         )
         webbuy: optional boolean
         buyer: 
         (
            username: optional string
            userId: integer range(1 - 4294967296)
            delegateId: optional integer range(1 - 4294967296)
            profileId: integer range(1 - 4294967296)
         )
         ware: 
         (
            id: 
            (
               string
               and
               more than 1 character
            )
         )
         contractId: optional integer range(0 - 4294967296)
      )
   )
   id: integer range(0 - 4294967296)
)

POST /sva/contracts/purchase/data

Purchases data associated with a given contract section.

Authentication: Required

Returns: The return value is currently not documented.

Input Validator

(
   date: regex("^[2-9][0-9]{3}-")
   section: 
   (
      
      (
         sellerSignature: string
         seller: 
         (
            username: optional string
            url: string
            userId: integer range(1 - 4294967296)
            profileId: integer range(1 - 4294967296)
            serverId: integer range(1 - 4294967296)
         )
         buyerSignature: string
         buyer: 
         (
            username: optional string
            userId: integer range(1 - 4294967296)
            delegateId: optional integer range(1 - 4294967296)
            profileId: integer range(1 - 4294967296)
            accountId: integer range(1 - 4294967296)
         )
         ware: 
         (
            mediaId: integer range(1 - 4294967296)
            payees: warepayees
            id: 
            (
               string
               and
               more than 1 character
            )
            description: optional string
         )
         contractId: integer range(1 - 4294967296)
      )
      and
      
      (
      
         (
            webbuy: equals true
            ware: 
            (
               fileInfos: 
               (
                  array
                  and
                  each item matches
                  (
                     contentType: string
                     extension: string
                     pieces: optional 
                     (
                        map
                        and
                        less than 0 characters
                     )
                     mediaId: integer range(1 - 4294967296)
                     size: integer range(1 - 4294967296)
                     id: string
                     contentSize: integer range(1 - 4294967296)
                  )
               )
            )
         )
         or
      
         (
            webbuy: optional equals false
            ware: 
            (
               fileInfos: 
               (
                  array
                  and
                  each item matches
                  (
                     contentType: string
                     extension: string
                     pieces: optional 
                     (
                        array
                        and
                        each item matches
                        (
                           index: integer range(0 - 4294967296)
                           ciphered: boolean
                           encrypted: boolean
                           sellerSignature: string
                           bfpSignature: string
                           pieceKey: optional 
                           (
                              data: string
                              length: integer range(1 - 4294967296)
                              algorithm: string
                           )
                           openKey: optional 
                           (
                              data: string
                              length: integer range(1 - 4294967296)
                              algorithm: string
                           )
                           sellerProfileId: integer range(1 - 4294967296)
                           bfpId: integer range(1 - 4294967296)
                           size: integer range(0 - 4294967296)
                        )
                     )
                     mediaId: integer range(1 - 4294967296)
                     size: integer range(1 - 4294967296)
                     id: string
                     contentSize: integer range(1 - 4294967296)
                  )
               )
            )
         )
      )
   )
)

GET /media/genres/<mediaType>

Retrieves the entire tree of genres for a given MediaType.

Authentication: Optional

Returns: HTTP 200 if successful and a nested map of genres, or an exception otherwise.

Path Parameters

mediaType - The type of media associated with a particular genre. Acceptable values include "audio", "book", "collection", "image", and "video".

GET /media/genres/<mediaType>

Retrieves a genre object for a given MediaType and genre ID.

Authentication: Optional

Returns: HTTP 200 and a genre object if successful, or an exception otherwise.

Path Parameters

mediaType - The type of media associated with a particular genre. Acceptable values include "audio", "book", "collection", "image", and "video".

POST /catalog/bundles

Creates a ware bundle according to the given media ID(s) and data preferences.

Authentication: Optional

Returns: The return value is currently not documented.

Input Validator

(
   mediaId: integer range(1 - 4294967296)
   preferences: 
   (
      array
      and
      each item matches
      (
         mediaIds: optional 
         (
            array
            and
            each item matchesinteger range(1 - 4294967296)
         )
         preferences: 
         (
            array
            and
            each item matches
            (
            
               (
                  contentType: regex("^audio/.+$")
                  minBitrate: integer range(1 - 4294967296)
               )
               or
            
               (
                  contentType: regex("^video/.+$")
                  videoCodec: string
               )
            )
         )
      )
   )
)

POST /sva/contracts/purchase/license

Purchases a license for the given media for a particular buyer.

Authentication: Required

Returns: The return value is currently not documented.

Input Validator

(
   
   (
      media: 
      (
         licenseAmount: precisemoney
         piecePayees: piecepayees
         publicDomain: boolean
         title: string
         ccLicenses: string
         payees: licensepayees
         signature: string
         releaseDate: regex("^[0-9]{4}-")
         buyerId: integer range(1 - 4294967296)
         signer: 
         (
            userId: integer range(1 - 4294967296)
            profileId: integer range(1 - 4294967296)
         )
         ownerId: integer range(1 - 4294967296)
         distribution: string
         payeeRules: 
         (
            array
            and
            each item matches
            (
               mediaId: integer range(0 - 4294967296)
               value: string
               type: string
            )
         )
         type: string
         id: integer range(1 - 4294967296)
      )
      version: equals "3.0"
      buyer: 
      (
         username: optional string
         userId: integer range(1 - 4294967296)
         delegateId: optional integer range(1 - 4294967296)
         profileId: integer range(1 - 4294967296)
         accountId: integer range(1 - 4294967296)
      )
      sections: optional 
      (
         map
         and
         less than 0 characters
      )
      id: integer range(0 - 0)
   )
   and

)

POST /catalog/netaccess/rtest

Performs a reverse network access test to ensure an in-the-wild sales server's catalog can be accessed via the internet. The message body must contain the sales server host, port, and URL path to post to and the token to post. If the given host is blank, the IP address of the caller will be used.

Authentication: Required

Returns: an HTTP 201 code if successful, an exception if not.

Input Validator

(
   token: 
   (
      string
      and
      less than 50 characters
   )
   host: string
   timeout: integer range(15 - 30)
   path: string
   sellerId: integer range(1 - 4294967296)
   port: integer range(1 - 65535)
)

GET /sva/bfp

Gets the BFP module for the given bfp ID, API version, operating system, and cpu type.

Authentication: Optional

Returns: The return value is currently not documented.

Query Validator

(
   os: string
   id: integer range(1 - 4294967296)
   apiVersion: string
   cpuType: string
)

Payswarm - Web API

Unofficial Draft 23 March 2010

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Network Participants

3. Content Transaction Overview

4. Base Technologies

4.1 REST

4.2 Javascript Object Notation

4.3 AES Cryptography Suite

4.4 RDFa

5. Discovery

5.1 API Discovery

5.2 Content Discovery

6. The Purchase Process

6.1 Media Discovery

6.2 License Selection

6.3 Asserting Purchase Preferences

6.4 Creating a Ware Bundle

6.5 Brokering a Non-Swarming Contract

6.6 Brokering a Swarming Contract

6.7 Negotiating with a Seller

6.8 Downloading a FilePiece

6.9 Purchasing the License

6.10 Purchasing the Data

6.11 Assembling the Data

7. Security Concerns

7.1 Identity Management

7.2 Digital Signatures

7.3 Encryption and Decryption

7.4 Identifying and Removing Troublemakers

7.5 Halting Content Distribution

8. API Reference

bfp

catalog

contract

financial

media

POST /payees/resolve

Input Validator

GET /catalog/server?nodeuser=A

Query Parameters

Query Validator

GET /catalog/sellerpools?fileId=A&mediaIds=B

Query Parameters

Query Validator

GET /catalog/sellerpools/<mediaId>

Path Parameters

GET /catalog/sellerpools/<mediaId>/<fileId>

Path Parameters

GET /catalog/payees/schemes?nodeuser=A

Query Parameters

GET /catalog/payees/schemes/<schemeId>?nodeuser=A

Path Parameters

Query Parameters

Query Validator

POST /catalog/payees/schemes?nodeuser=A

Query Parameters

Query Validator

Input Validator

POST /catalog/payees/schemes/<schemeId>?nodeuser=A

Path Parameters

Query Parameters

Query Validator

Input Validator

DELETE /catalog/payees/schemes/<schemeId>?nodeuser=A

Path Parameters

Query Parameters

Query Validator

GET /sva/contracts/sections/<contractId>/<sellerId>

Path Parameters

POST /catalog/netaccess/test?nodeuser=A

Query Parameters

Query Validator

Input Validator

GET /media/related/<mediaId>?num=A&relationship=B&start=C

Path Parameters

Query Parameters