drwasho/OpenBazaar REST API - POST calls.md

## OpenBazaar REST API - POST calls.md

      
    Raw
  

              OpenBazaar REST API - POST calls.md
            
          
    OpenBazaar REST API Documentation

OpenBazaar has two distinct components: a server and a client. 
The ‘server’ is the network daemon that connects with the OpenBazaar P2P network and contains the node’s database. It is the ‘business end’ of the OpenBazaar application, as it connects directly with other nodes on the network, caches data, digital signs contracts, and holds private keys etc. The server can either run locally (i.e. on your computer) or remotely on a virtual private server (e.g. Digital Ocean, Docker, Heroku).
The ‘client’ is what the user interacts with operate the functions of the server. The client uses a combination of REST and Websocket (WS) APIs to control the network and market function of the server. This enables developers to create alternative or feature-specific clients for OpenBazaar.
If the OpenBazaar server is running locally, the base URL will be:
http://localhost:18469/api/v1/
If the server is hosted remotely, ‘localhost’ is replaced by the IP address of the remote server. For example:
http://128.199.118.253:18469/api/v1/
For remote access, the server must be run with the necessary arguments to support remote network access. We will link to documentation explaining how to do this soon.
The response format is JSON, with exception to image API calls.

POST API Calls

POST follow

Follows a target node and will cause you to receive notifications from that node after certain event (e.g. new listing, broadcast messages) and share some metadata (in future).
Resource URL

http://localhost:18469/api/v1/follow
Arguments


guid=[target node guid]

Response


{"success": "true"}
{"success": "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/follow" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="guid" placeholder="Target Node GUID" /><br><br>
        <input type="submit" value="Follow" />`
    </form>
</body>
</html>

POST unfollow

Stop following a target node, will cease to receive notifications and sharing metadata.
Resource URL

http://localhost:18469/api/v1/unfollow
Arguments


guid=[Target node GUID]

Response


{"success": "true"}
{"success": "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/unfollow" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="guid" placeholder="Target Node GUID" /><br><br>
        <input type="submit" value="Follow" />`
    </form>
</body>
</html>

POST profile

Add data related to the node's profile into the database, which will be visible to other nodes.
Resource URL

http://localhost:18469/api/v1/profile
Arguments


name=[user-generated name]

String
Required

Must be set on the firt call to create the profile, but can be omitted on subsequent calls to update other fields in the profile


location=[country code]

Required

Must be set on the firt call to create the profile, but can be omitted on subsequent calls to update other fields in the profile


handle=[Blockchain ID handle]

String starting with @
The Blockchain ID handle starting with “@”
Eventually this will be required to resolve to the guid


about=[text]

String
'About' text for the store


short_description=[text]

String
Text to show in the homepage store list (string)


nsfw=[true,false]

Boolean
Is this user profile/store nsfw? Will default to false if the field is omitted. (“true” or “false”)


vendor=[true,false]

Boolean
Is this user a vendor? must be set to true if so. defaults to false if omitted. (“true” or “false”)


moderator=[true,false]

Boolean
Is this user a moderator? must be set to true if so. defaults to false if omitted. (“true” or “false”)


website=[URL]

String
A website for this user (string)


email=[email address]

String
An email address for this user (string)


primary_color=[number]

Integer
Hex color formatted in base 10. For example, 00FF00 should be sent as “65280” (string of base 10 formatted hex color)


secondary_color=[number]

Integer
Same as primary color


text_color=[number]

Integer
Same as primary color


background_color=[number]

INteger
Same as primary color


avatar=[image hash]

String
The hash of the avatar image. must have been previously uploaded using the upload_image api call (40 character hex string)


header=[image hash]

String
The hash of the header image. must have been previously uploaded using the upload_image api call. (40 character hex string)


pgp_key=[public key block]

String
A pgp public key to include in the profile. if included the signature field must also be included. (string pgp public key block)


Response


{"success": "true"}
{"success": "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/profile" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="name" placeholder="Name" required /><br><br>
        <input type="text" name="location" placeholder="Location" required /><br><br>
        <input type="text" name="handle" placeholder="Blockchain ID Handle" /><br><br>
        <input type="text" name="about" placeholder="About Text" /><br><br>     
        <input type="text" name="short_description" placeholder="Short Description Text" /><br><br>     
        <input type="text" name="nsfw" placeholder="NSFW? True or False" /><br><br>     
        <input type="text" name="vendor" placeholder="Vendor? True or False" /><br><br>     
        <input type="text" name="moderator" placeholder="Moderator? True or False." /><br><br>      
        <input type="text" name="website" placeholder="Website" /><br><br>      
        <input type="text" name="email" placeholder="Email" /><br><br>      
        <input type="number" name="primary_color" placeholder="Primary color hex (base 10; e.g. 65280)" /><br><br>      
        <input type="number" name="secondary_color" placeholder="Secondary color hex (base 10; e.g. 65280)" /><br><br>      
        <input type="number" name="background_color" placeholder="Background color hex (base 10; e.g. 65280)" /><br><br>        
        <input type="text" name="avatar" placeholder="Avatar image hash" /><br><br>     
        <input type="text" name="header" placeholder="Header image hash" /><br><br>     
        <input type="text" name="pgp_key" placeholder="PGP public key" /><br><br>       
        <input type="submit" value="Submit Profile Data" />`
    </form>
</body>
</html>

POST social_accounts

Adds a social account to the user profile data of the user.
Resource URL

http://localhost:18469/api/v1/social_accounts
Arguments


account_type=[social account]

Required
String
Options (must be one of these; case sensitive):

facebook
twitter
instagram
snapchat


username=[username]

Required
String


proof=[URL]

URL proving ownership of the social account
Presently not validated


Response


{"success": "true"}
{"success": "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/social_accounts" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="account_type" placeholder="Account type" required /><br><br>
        <input type="text" name="username" placeholder="Account username" required /><br><br>
        <input type="text" name="proof" placeholder="URL proof of ownership" /><br><br>
        <input type="submit" value="Add Social Account" />`
    </form>
</body>
</html>

POST make_moderator

Sets your node as a Moderator, which is discoverable on the network.
Resource URL

http://localhost:18469/api/v1/make_moderator
Arguments

None.
Response


{"success": "true"}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/make_moderator" method="post" enctype="multipart/form-data" target="_blank">
        <input type="submit" value="Become a Moderator" />`
    </form>
</body>
</html>

POST  unmake_moderator

Removes the node as a Moderator and is no longer discoverable on the network as a Moderator.
Resource URL

http://localhost:18469/api/v1/unmake_moderator
Arguments

None.
Response


{"success": "true"}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/unmake_moderator" method="post" enctype="multipart/form-data" target="_blank">
        <input type="submit" value="Stop being a Moderator" />`
    </form>
</body>
</html>

POST contracts

Creates a listing contract, which is saved to the database and local file system, as well as publish the keywords in the distributed hash table.
Resource URL

http://localhost:18469/api/v1/contracts
Arguments


expiration_date=[UTC]

Sormatted string
The date the contract should expire in string formatted UTC datetime
Example:

"2015-11-01T00:00 UTC"
“” if the contract never expires


metadata_category=[category]

Formatted string
Select from:

physical good
digital good
service


title=[title text]

String
Title of the product for sale


description=[description text]

String
Description of the item, content or service


currency_code=[code]

Formatted string
The currency the product is priced in. may either be “btc” or a currency from this list


price=[value]

String
The price per unit in the same currency as currency_code.


process_time=[time]

String
The time it will take to prepare the item for shipping


nsfw=[true/false]

Boolean
Is the item not suitable for work (i.e. 18+)


shipping_origin=[country/region]

Formatted string
Required and only applicable if the metadata_category is a physical good
Where the item ships from
Must be a formatted string from this list


shipping_regions=[locations]

Formatted string
Required and only applicable if the metadata_category is a physical good
A list of countries/regions where the product will ship to
Each item in the list must be formatted from this list


est_delivery_domestic=[time]

Estimated delivery time for domestic shipments


est_delivery_international=[time]

String
Estimated delivery time for international shipments


terms_conditions=[terms and conditions text]

String
Any terms or conditions the user wishes to include


returns=[returns policy text]

String
Return policy


shipping_currency_code=[currency code]

Formatted string
The currency code used to price shipping. may either be “btc” or a currency from this list


shipping_domestic=[price]

String
The price of domestic shipping in the selected currency code


shipping_international=[price]

String
The price of nternational shipping in the selected currency code


keywords=[keyword text]

String
A list of string search terms for the listing
Must be fewer than 10


category=[category text]

Sting
A user-generated category for this product
Will show in store’s category list


condition=[condition text]

The condition of the product


sku=[sku text]

String
Stock keeping unit (sku) for the listing


images=[image hash]

40 character hex string
A list of SHA256 image hashes
The images should be uploaded using the upload_image api call


free_shipping=[boolean]

"true" or "false"


moderators=[guids]

GUID: 40 character hex string
A list of moderator GUIDs that the vendor wishes to use
Note: the moderator must have been previously returned by the get_moderators websocket call.
Given the UI workflow, this call should always be made before the contract is set.


options=[options text]

String
A list of options for the product
Example: “size”, “color”
option=[option text]

String
For each option in the options list, another argument should be added using that option name and a list of value
For example, given “color” in the options list, choose from "red", "green", "purple" etc


Response


{"id": "", "success": true}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/contracts" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="title" placeholder="Title" required/><br><br>
        <input type="text" name="description" placeholder="Description" required /><br><br>
        <input type="text" name="currency_code" placeholder="Currency Code" required /><br><br>
        <input type="text" name="price" placeholder="Price" required /><br><br>
        <input type="text" name="process_time" placeholder="Process Time" /><br><br>
        <input type="text" name="nsfw" placeholder="Not suitable for work?" /><br><br>
        <input type="text" name="keywords" placeholder="Keywords" /><br><br>
        <input type="text" name="category" placeholder="Category" /><br><br>
        <input type="text" name="condition" placeholder="Condition of the item" /><br><br>
        <input type="text" name="sku" placeholder="SKU" /><br><br>
        <input type="text" name="images" placeholder="Image hashes" /><br><br>
        <input type="text" name="moderators" placeholder="Moderator GUIDs" /><br><br>
        <input type="text" name="options" placeholder="Listing Options" /><br><br>
        <input type="text" name="expiration_date" placeholder="Expiration date for the listing" /><br><br>
        <input type="text" name="metadata_category" placeholder="Physical item, digital content, or service." /><br><br>
        <input type="text" name="free_shipping" placeholder="Free shipping?" /><br><br>
        <input type="text" name="shipping_origin" placeholder="Shipping origin" /><br><br>
        <input type="text" name="shipping_regions" placeholder="Shipping Regions" /><br><br>
        <input type="text" name="est_delivery_domestic" placeholder="Estimated delivery time for domestic deliveries." /><br><br>
        <input type="text" name="est_delivery-international" placeholder="Estimated delivery time for international deliveries." /><br><br>
        <input type="text" name="shipping_domestic" placeholder="Price for domestic shipping" /><br><br>
        <input type="text" name="shipping_international" placeholder="Price for international shipping" /><br><br>
        <input type="text" name="terms_conditions" placeholder="Terms and Conditions of sale." /><br><br>
        <input type="text" name="returns" placeholder="Returns policy for the listing." /><br><br>
        <input type="submit" value="Create Listing" />
    </form>
</body>
</html>

POST purchase_contract

Purchases a contract by sending the purchase into the Vendor. The Buyer waits for a response to indicate whether the purchase is successful or not. If successful, the Buyer needs to fund the direct or multisig address.
Resource URL

http://localhost:18469/api/v1/purchase_contract
Arguments


id=[contract id]

40 character hex string
The contract id to be purchased
Note: the contract must be in cache, meaning it must have been called specifically at least once.


quantity=[quantity]

String
Number of items to be purchased


ship_to=[name]

String
Name of the person that the item will be shipped to


address=[street address]

String
Street address for delivery of the item


city=[name of city]

String
Name of the city corresponding to the address


state=[name of state]

String
Name of the state corresponding to the address


postal_code=[postcode of the delivery address]

String
Postal code corresponding to the address


moderator=[GUID]

40 character hex string
The Moderator, listed in the original contract, chosen by the buyer
This is omitted if there is a direct payment


options=[options for the listing]

String
E.g. "color"
option=[option from options]

String
E.g. "red"


Response

{
    "success" : true, 
    "address" : "bitcoin address to fund", 
    "amount" : "amount to fund",
    "order_id" : "purchase order id"
}
Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/purchase_contract" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="id" placeholder="Contract ID" /><br><br>
        <input type="text" name="quantity" placeholder="Quantity" /><br><br>
        <input type="text" name="ship_to" placeholder="Name of recipient" /><br><br>
        <input type="text" name="address" placeholder="Street Address" /><br><br>
        <input type="text" name="city" placeholder="City" /><br><br>
        <input type="text" name="state" placeholder="State" /><br><br>
        <input type="text" name="postal_code" placeholder="Postcode" /><br><br>
        <input type="text" name="moderator" placeholder="Moderator GUID" /><br><br>
        <input type="text" name="options" placeholder="Option" /><br><br>
        <input type="submit" value="Place Order" />`
    </form>
</body>
</html>

POST confirm_order

Sends the order confirmation and shipping information to the Buyer. If he’s offline, it will embed this data into the dht. The API call also updates the status of the order in the database.
Resource URL

http://localhost:18469/api/v1/confirm_order
Arguments


id=[order id]

40 character hex string
ID of the order placed by the Buyer
This only applies to orders that have been funded


shipper=[name of shipper]

String
For physical goods to be delivered


tracking_number=[shipping tracking number]

String
For physical goods to be delivered


est_delivery=[estimated delivery of item]

String
Based on the feedback from the shipper, an up to date estimate of delivery.


url=[link to digital content]

Formatted string
For digital content only


password=[password to access digital content]

String
To decrypt and/or access protected digital content


Response


{"success" : "true"}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/confirm_order" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="id" placeholder="Purchase order ID" required /><br><br>
        <input type="text" name="shipper" placeholder="Name of the Shipper" /><br><br>
        <input type="text" name="tracking_number" placeholder="Shuipping tracking number" /><br><br>
        <input type="text" name="est_delivery" placeholder="Estimated delivery time" /><br><br>
        <input type="text" name="url" placeholder="URL to digital content" /><br><br>
        <input type="text" name="password" placeholder="Password to access digital content" /><br><br>
        <input type="submit" value="Confirm Order" />`
    </form>
</body>
</html>

POST complete_order

Sends a message with a partially signed transaction releasing funds from escrow to the Vendor as well as review data.
Resource URL

http://localhost:18469/api/v1/complete_order
Arguments


id=[order id]

40 character hex string


feedback=[feedback rating]

String: 1-5
Overall rating of the transaction


quality=[item quality rating]

String: 1-5
Rating of the quality of the item, content, or service


description=[item description rating]

String: 1-5
Rating of the listing description of the item, content, or service


delivery_time=[delivery time rating]

String: 1-5
Rating of the time taken to deliver the item


customer_service=[customer service rating]

String: 1-5
Rating of the customer service displayed by the Vendor


review=[free form review text]

String (<= 80 characters)
Free text to review the transaction


Response


{"success" : "true" }
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/complete_order" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="id" placeholder="Order ID" required /><br><br>
        <input type="text" name="feedback" placeholder="Feedback Rating" /><br><br>
        <input type="text" name="quality" placeholder="Item Quality Rating" /><br><br>
        <input type="text" name="description" placeholder="Listing Description Rating" /><br><br>
        <input type="text" name="delivery_time" placeholder="Delivery Time Rating" /><br><br>
        <input type="text" name="customer_service" placeholder="Customer Service Rating" /><br><br>
        <input type="text" name="review" placeholder="Review" /><br><br>
        <input type="submit" value="Confirm Order" />`
    </form>
</body>
</html>

POST upload_image

@POST('^/api/v1/upload_image')
    arguments:
        image= a list of product images to upload (LIST of images in base64. data only, no base64 prefix)
        avatar= use this if uploading an avatar image (base64 image)
        header= use this if uploading a header image (base64 image)
    action:
        saves the image in the file system and a pointer to it in the db
    return:
        {success: True, image_hashes: [list_of_image_hashes]}

Resource URL

http://localhost:18469/api/v1/upload_image
Arguments


image=[base 64 image data]

Base 64, no prefix


avatar=[base 64 image data]

Base 64, no prefix
Use if uploading an avatar image


header=[base 64 image data]

Base 64, no prefix
Use if uploading a store header image


Response


{"success" : "true", "image_hashes" : [list_of_image_hashes] }
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/upload_image" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="image" placeholder="Base64 Image" /><br><br>
        <input type="text" name="avatar" placeholder="Base64 Avatar Image" /><br><br>
        <input type="text" name="header" placeholder="Base64 Header Image" /><br><br>
        <input type="submit" value="Upload Images" />`
    </form>
</body>
</html>

POST settings

Changes the settings of the node and pushes them to the database.
Resource URL

http://localhost:18469/api/v1/settings
Arguments

All fields are required.

refund_address=[bitcoin address]

String
If a transaction is refunded, bitcoins will be sent to this address


currency_code=[currency]

Formatted string
Sets the price of listings displayed in the client


country=[country]

Formatted string
Sets the country of origin


language=[language]

String
Language used in the client


time_zome=[time zone]

String
Timezone of the user


notifications=[true, false]

Boolean
Whether notifications are shown in the client


shipping_addresses=[address list]

String
Will be used to determine if an item can be shipped to the user's location


blocked=[GUIDs]

40 character hex string
Nodes that the user will not retrieve and display data from


libbitcoin_server=[server URL]

URL string
If blank, it will default to the hardcoded libbitcoin servers in the server repository


ssl=[true, false]

Boolean
Sets whether SSL is used to communicate with the server


terms_conditions=[terms and conditions text]

String
Terms and conditions to be added by default to all listings, unless overwritten in the listing process


refund_policy=[refund policy text]

String
Refund policy to be added by default to all listings, unless overwritten in the listing process


Response


{"success" : "true"}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/settings" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="refund_address" placeholder="Bitcoin Refund Address" required /><br><br>
        <input type="text" name="currency_code" placeholder="Currency Code" required /><br><br>
        <input type="text" name="country" placeholder="Country" required /><br><br>
        <input type="text" name="language" placeholder="Language" required /><br><br>
        <input type="text" name="time_zone" placeholder="Time Zone" required /><br><br>
        <input type="text" name="notifications" placeholder="Notifications (true/false)" required /><br><br>
        <input type="text" name="shipping_addresses" placeholder="Shipping Addresses" required /><br><br>
        <input type="text" name="blocked" placeholder="Blocked Nodes (GUID)" required /><br><br>
        <input type="text" name="libbitcoin_server" placeholder="Libbitcoin Server URL" required /><br><br>
        <input type="text" name="ssl" placeholder="SSL (true/false)" required /><br><br>
        <input type="text" name="terms_conditions" placeholder="Terms and Conditions" required /><br><br>
        <input type="text" name="refund_policy" placeholder="Refund Policy" required /><br><br>
        <input type="submit" value="Change Settings" />`
    </form>
</body>
</html>

POST mark_notification_as_read

Marks a notification as read in the database.
Resource URL

http://localhost:18469/api/v1/mark_notification_as_read
Arguments


id=[id of the notification]

40 character hex string
Every notification has an ID that must be referenced in order to mark as read


Response


{"success" : "true"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/mark_notification_as_read" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="id" placeholder="Notification ID" /><br><br>
        <input type="submit" value="Mark As Read" />`
    </form>
</body>
</html>

POST mark_chat_message_as_read

Marks all chat messages with a specific node as read in the database.
Arguments


guid=[guid of node]

40 character hex string
GUID of the party you are chatting with


Response


{"success" : "true"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/mark_chat_as_read" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="guid" placeholder="GUID" /><br><br>
        <input type="submit" value="Mark Chat As Read" />`
    </form>
</body>
</html>

POST broadcast

Sends a Twitter-like message to all nodes that are following you.
Resource URL

http://localhost:18469/api/v1/broadcast
Arguments


message=[message to send]

String
140 characters or less


Response


{"success" : "true", "peers_reached" : [number reached] }

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/broadcast" method="post" enctype="multipart/form-data" target="_blank">
        <input type="text" name="message" placeholder="Message" /><br><br>
        <input type="submit" value="Broadcast Message to Followers" />`
    </form>
</body>
</html>

POST check_for_payment

Sends a Twitter-like message to all nodes that are following you.
Resource URL

http://localhost:18469/api/v1/check_for_payment
Arguments

None.
Response


{"success" : "true"}
{"success" : "false"}

Quickstart Example

<html>
<body>
    <form action="http://localhost:18469/api/v1/check_for_payment" method="post" enctype="multipart/form-data" target="_blank">
        <input type="submit" value="Check for Payment" />`
    </form>
</body>
</html>