Linden Lab Official:Viewer Managed Marketplace/Marketplace API for Viewers

From Second Life Wiki
Jump to navigation Jump to search
NOTE: This is an official Second Life API provided and documented by Linden Lab. Its use is subject to the API Terms of Use.

Get Merchant

Find out if the agent_id is a merchant.

Verb and Path: GET /merchant

If the agent_id is a merchant, HTTP status code 200 is returned with no body.

If the agent_id is not a merchant, HTTP status code 404 is returned with no body.


Viewer’s implementation:

  • Call : LLMarketplaceData::initializeSLM()
  • Responder : LLSLMGetMerchantResponder()

Marketplace Listing Data Dictionary

The marketplace data is serialized into JSON. The table below describes each attribute exposed through the API. While there are many attributes for the marketplace products and variants table (what this API maps to), all attributes which are not defined by this dictionary are automatically filtered out for security and data integrity.

Name Description Example
id Type: integer

The marketplace’s listing id. From the marketplace products table.

Read-only

Valid: 1234 Invalid: “foo”, “1234”

name Type: string

The marketplace’s listing name. From the marketplace products table. This attribute is only exposed for the POST (create) API call.

Any string up to 255 characters. Cannot be blank.

“::Mesh:: Penguin Mini Avatar CUTE!!”

is_listed Type: boolean

The listing status of the listing. This maps to the marketplace table/column products.current_state. If the current_state is ‘listed’ this value will be true, false otherwise.

Valid: true, false

Invalid: “true”, “false”

edit_url Type: string

The Marketplace edit product URL. Provided so the viewer has a direct link for the merchant to edit the product.

Read-only

Valid: “https://marketplace.secondlife.com/merchants/1234/store/products/4567/edit”

inventory_info.count_on_hand Type: integer

The listings number of available inventory for disbursement. Examples of the three different “count on hand” or “inventory stock” states are listed in the examples.

Valid:
  • -1 (unlimited)
  • 0 (out of stock)
  • 9000 (plenty of inventory)

Invalid: “-1”, “0”, “9000”, “unlimited”, ...

inventory_info.listing_folder_id Type: string (UUID)

The listing folder’s id marketplace has on file for the inventory link. If inventory is not associated, a 0-filled UUID will be returned.

Valid:

"a38ae2aa-7435-4dbb-ad1a-53f443453441" (listing associated with inventory) "00000000-0000-0000-0000-000000000000" (listing not associated with inventory) Invalid: 000000000-0000-0000-00000000, “listing-id-9000”

inventory_info.version_folder_id Type: string (UUID)

The version folder’s id marketplace has on file for the inventory link. If inventory is not associated, a 0-filled UUID will be returned. This is the folder id marketplace will use to request deliveries.

Valid:

"a38ae2aa-7435-4dbb-ad1a-53f443453441" (listing associated with inventory) "00000000-0000-0000-0000-000000000000" (listing not associated with inventory) Invalid: 000000000-0000-0000-00000000, “listing-id-9000”

Get Listings

Get the marketplace listings for the agent_id.

Verb and Path: GET /listings

If the agent_id is not a merchant, HTTP status code 404 is returned with no body.

If the agent_id is a merchant, HTTP status code 200 is returned with the following JSON payload in the body: 

{
   "listings":[
      {
         "id":1180335,
         "is_listed":false,
"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180335/edit",
         "inventory_info":{
            "count_on_hand":-1,
            "listing_folder_id":"00000000-0000-0000-0000-000000000000",
            "version_folder_id":"00000000-0000-0000-0000-000000000000"
         }
      },
      {
         "id":1180336,
         "is_listed":false,
"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180336/edit",
         "inventory_info":{
            "count_on_hand":-1,
            "listing_folder_id":"00000000-0000-0000-0000-000000000000",
            "version_folder_id":"00000000-0000-0000-0000-000000000000"
         }
      }
   ]
}

Viewer’s implementation:

  • Call : LLMarketplaceData::getSLMListings()
  • Responder : LLSLMGetListingsResponder()


Get Listing

Get the marketplace listing for listing_id.

Verb and Path: GET /listing/:listing_id

If the agent_id does not own the listing_id, HTTP status code 404 is returned with no body.

If the agent_id owns the listing_id, HTTP status code 200 is returned with the following JSON payload in the body: 

{
   "listings":[
      {
         "id":1180335,
         "is_listed":false,
"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180335/edit",
         "inventory_info":{
            "count_on_hand":-1,
            "listing_folder_id":"00000000-0000-0000-0000-000000000000",
            "version_folder_id":"00000000-0000-0000-0000-000000000000"
         }
      }
   ]
}

Viewer’s implementation:

  • Call : LLMarketplaceData::getSLMListing()
  • Responder : LLSLMGetListingResponder()


Create a Listing

Create a listing on the marketplace from agent_id (merchant’s) inventory. Verb and Path: POST /listings If the agent_id is not a merchant, HTTP status code 404 is returned with no body. If the agent_id is a merchant, and the payload does not pass validations, HTTP status code 422 (The validation messages will not be included in the production release) The fields listing.name and listing.inventory_info.listing_folder_id are required. The fields listing.inventory_info.count_on_hand, listing.inventory_info.version_folder_id are optional. If the agent_id is a merchant, HTTP status code 201 is returned with the following JSON payload in the body (outlined below the sample request body):

A sample request body could look like this: 

{
   "listing":{
      "name":"Test Listing",
      "inventory_info":{
         "listing_folder_id":"e3ef6257-2cd8-4126-8dba-49a9c13c65e5",
         "version_folder_id":"d4bc9801-36e4-49fa-97ca-a5a9b210d57c"
      }
   }
}


The response should be something like: 

HTTP/1.1 201 Created 
Content-Type: application/json; charset=utf-8
X-Ua-Compatible: IE=Edge
Etag: "6cdc8f4b68ae40b2e7853f0f75d6ad02"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7d60598899a8f70ad2aed167667490e9
X-Runtime: 0.132662
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-11-10)
Date: Thu, 17 Apr 2014 21:18:36 GMT
Content-Length: 165
Connection: Keep-Alive
`n_slm_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFRkkiJTQ1NjIzN2ZmNzZlODE1YmM1MTY4YmRiZTcwOGM0ZmE2BjsAVA%3D%3D--827c91281160a5911cb7a6f4e0f3cfd335216b2d; path=/; HttpOnly

{"listings":[{"id":1180554,"is_listed":false,"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180554/edit","inventory_info":{"count_on_hand":-1,"listing_folder_id":"e3ef6257-2cd8-4126-8dba-49a9c13c65e5","version_folder_id":"d4bc9801-36e4-49fa-97ca-a5a9b210d57c"}}]}

Viewer’s implementation:

  • Call : LLMarketplaceData::createSLMListing()
  • Responder : LLSLMCreateListingsResponder()

Modify a Listing

Modify a marketplace listing_id owned by agent_id.

Verb and Path: PUT /listing/:listing_id (PATCH will be supported at a later time)

If the agent_id does not own listing_id, HTTP status code 404 is returned with no body.

If the agent_id is a merchant, but the listing_id is invalid, HTTP status code 404 is returned with no body.

If the agent_id is a merchant, and the agent_id owns the listing_id, but if the payload is malformed or it does not pass validations, HTTP status code 422 is returned with no body.

If the agent_id owns listing_id, HTTP status code 200 is returned with the JSON representation of the modified data as a payload in the body.

KBnote.png Note: Not all fields are required to be included in the payload, only include the fields that need to be changed.


Here is an example of a valid payload, asking to change only the inventory_info.count_on_hand: 

{
   "listing":{
      "id": 1180548,
      "inventory_info":{
         "count_on_hand":5
      }
   }
}

Here is what the response to the above should look like: 

HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8
X-Ua-Compatible: IE=Edge
Etag: "1d9498bf726ee1331ece640bbd73d5d4"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 07ce9ce12d0865c590c05db87ea9aa1d
X-Runtime: 1.127898
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-11-10)
Date: Mon, 21 Apr 2014 23:50:11 GMT
Content-Length: 214
Connection: Keep-Alive
Set-Cookie: _slm_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFRkkiJTZiNmM1MzU1MDA0NDY5NDViMTVmNWMzMDBjNDYwNDNiBjsAVA%3D%3D--ca9ddfb6783cba137f7af5760bee31c0e2fee516; path=/; HttpOnly

{"listings":{"id":1180548,"is_listed":false,"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180548/edit","inventory_info":{"count_on_hand":5,"listing_folder_id":"00000000-0000-0000-0000-000000000000","version_folder_id":"00000000-0000-0000-0000-000000000000"}}}

Here is what a bad response looks like: 

HTTP/1.1 422 Unprocessable Entity 
Content-Type: application/json; charset=utf-8
X-Ua-Compatible: IE=Edge
Cache-Control: no-cache
X-Request-Id: 520fd646cc83d2ea501d99f49e4c593e
X-Runtime: 0.053630
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-11-10)
Date: Wed, 07 May 2014 21:14:06 GMT
Content-Length: 113
Connection: Keep-Alive
Set-Cookie: _slm_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFRkkiJWM2ZWEzOGZlNzUwNjA0NGRmZTZhNDA4NDZkYWNhMGViBjsAVA%3D%3D--558dd85290f1df222137b6551ba7334c5177064f; path=/; HttpOnly

{"listings":{"id":1180548,"is_listed":false,"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180548/edit","inventory_info":{"count_on_hand":5,"listing_folder_id":"00000000-0000-0000-0000-000000000000","version_folder_id":"00000000-0000-0000-0000-000000000000"}}}

Viewer’s implementation:

  • Call : LLMarketplaceData::updateSLMListing()
  • Responder : LLSLMUpdateListingsResponder()

Associate Inventory

Associate a version_folder_id with a marketplace listing_id. This is to force a version_folder_id to be linked to a marketplace listing_id when something goes awry.

Verb and Path: PUT /associate_inventory/:listing_id

If the agent_id is not a merchant, HTTP status code 404 is returned with no body.

If the agent_id does not own the listing_id, HTTP status code 404 is returned with no body.

If the agent_id is a merchant, but the supplied listing_id doesn’t exist, HTTP status code 404 is returned with no body.

If the agent_id is a merchant and the listing_id is owned by the merchant, but the listing_folder_id or version_folder_id do not pass the UUID validation, HTTP status code 422 is returned with no body.

If the agent_id owns the listing_id, and there is no existing version_folder_id or listing_folder_id linked to the listing_id, the listing_folder_id and version_folder_id are linked to the listing_id and the listing remains unlisted on the marketplace. HTTP status code 200 is returned with a json payload outlined below.

If the agent_id owns the listing_id, but the version_folder_id is already associated with marketplace listing A, the listing which is using version_folder_id is automatically unlisted and the listing_folder_id and version_folder_id links are removed. After the links are removed from the listing which previously linked to version_folder_id, the listing_folder_id and version_folder_id are linked to the listing_id for listing B specified in the URI. The marketplace’s state of listing B remains unchanged. HTTP status code 200 is returned with a json payload outlined below.

KBnote.png Note: The id, version_folder_id and listing_folder_id attributes are the only attributes which are accepted for this call. If more attributes are supplied, they will be ignored.

Here is a sample of a valid payload: 

{
   "listing":{
      "id": 1180548,
      "inventory_info":{
         "listing_folder_id":"e3ef6257-2cd8-4126-8dba-49a9c13c65e5",
         "version_folder_id":"d4bc9801-36e4-49fa-97ca-a5a9b210d57c"
      }
   }
}


And its response: 

HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8
X-Ua-Compatible: IE=Edge
Etag: "1d9498bf726ee1331ece640bbd73d5d4"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 07ce9ce12d0865c590c05db87ea9aa1d
X-Runtime: 1.127898
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-11-10)
Date: Mon, 21 Apr 2014 23:50:11 GMT
Content-Length: 214
Connection: Keep-Alive
Set-Cookie: _slm_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFRkkiJTZiNmM1MzU1MDA0NDY5NDViMTVmNWMzMDBjNDYwNDNiBjsAVA%3D%3D--ca9ddfb6783cba137f7af5760bee31c0e2fee516; path=/; HttpOnly

{"listings":[{"id":1180548,"is_listed":false,"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1180548/edit","inventory_info":{"count_on_hand":5,"listing_folder_id":"e3ef6257-2cd8-4126-8dba-49a9c13c65e5","version_folder_id":"d4bc9801-36e4-49fa-97ca-a5a9b210d57c"}}]}

Viewer’s implementation:

  • Call : LLMarketplaceData::associateSLMListing()
  • Responder : LLSLMAssociateListingsResponder()

Delete a Listing

Delete a marketplace listing_id. This is to remove a marketplace listing.

Verb and Path: DELETE /listing/:listing_id

If the agent_id is not a merchant, HTTP status code 404 is returned with no body.

If the agent_id does not own the listing_id, HTTP status code 404 is returned with no body.

If the agent_id is a merchant, but the supplied listing_id doesn’t exist, HTTP status code 404 is returned with no body.

If the agent_id is a merchant and owns the listing_id, the listing_id is archived and no longer visible to the merchant, all end users and the Marketplace API. The listing_folder_id and the version_folder_id links are released and can be re-associated with the marketplace with a new or existing listing. HTTP status code 200 is returned with a json payload outlined below.

If the agent_id is a merchant and owns the listing_id, but the listing_id cannot be deleted (archived), HTTP status code 422 is given back with no body.


An example of a valid request to delete a listing: 

DELETE /listing/1234

(no body is included)

And its response: 

HTTP/1.1 200 OK 
Content-Type: application/json; charset=utf-8
X-Ua-Compatible: IE=Edge
Etag: "1d9498bf726ee1331ece640bbd73d5d4"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 07ce9ce12d0865c590c05db87ea9aa1d
X-Runtime: 1.127898
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-11-10)
Date: Mon, 21 Apr 2014 23:50:11 GMT
Content-Length: 214
Connection: Keep-Alive
Set-Cookie: _slm_session=BAh7BkkiD3Nlc3Npb25faWQGOgZFRkkiJTZiNmM1MzU1MDA0NDY5NDViMTVmNWMzMDBjNDYwNDNiBjsAVA%3D%3D--ca9ddfb6783cba137f7af5760bee31c0e2fee516; path=/; HttpOnly

{"listings":[{"id":1234,"is_listed":false,"edit_url":"https://marketplace.secondlife.com/merchants/220931/store/products/1234/edit","inventory_info":{"count_on_hand":5,"listing_folder_id":"e3ef6257-2cd8-4126-8dba-49a9c13c65e5","version_folder_id":"d4bc9801-36e4-49fa-97ca-a5a9b210d57c"}}]}

Viewer’s implementation:

  • Call : LLMarketplaceData::deleteSLMListing()
  • Responder : LLSLMDeleteListingsResponder()
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Viewer_Managed_Marketplace/Marketplace_API_for_Viewers&oldid=1193827"