Skip to content

Tag Management API: Individual Tags

Jump to bottom Edit New page
Gene Stevens edited this page Mar 10, 2012 · 3 revisions

For creating, updating, retrieving and deleting individual tags provisioned in the system.

Overview

These APIs exist to allow for the creation, update, configuration and removal of individual Tags in our system. The "itemID" used in these URIs is any unique identifier that is meaningful to you, ideally the same as your inventory SKUs or something with a similar persistent meaning. There is no limit to the number of tags you can create.

We have two URI formats for convenience

  1. One based around the Item IDs that are generated by your system
  2. One based around the Short Item IDs generated by our system

Depending on your use case, you may find one or the other easier to integrate. Since Short IDs are automatically generated by our system, they cannot be specified when creating or updating tags.

URI for Item IDs

  • Format /tags/item/{itemID}
  • Verbs GET, POST, PUT, DELETE

Notes

  • {itemID} can be no larger than 64 characters
  • {itemID} must be properly URL-encoded in order to successfully store and retrieve it later
  • {itemID} is case-sensitive! E.g., "Item-001" and "item-001" are different IDs.

URI for Short Item IDs

  • Format /tags/short_item/{shortItemID}
  • Verbs GET, PUT, DELETE

Notes

  • {shortItemID} is between 4 and 10 characters: a-z, 0-9
  • POST is not relevant for this URI since Short Item IDs are automatically generated. Instead, use POST against the Item ID URI described above.

GET

Retrieves a single tag from the system

Example Item ID curl request

curl -v -X GET \
	 -H 'X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648' \
	 "https://api.taglabsinc.com/tags/item/item-0001"

> GET /tags/item/item-0001 HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
>

Example Short Item ID curl request

curl -v -X GET \
	 -H 'X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648' \
	 "https://api.taglabsinc.com/tags/short_item/889j"

> GET /tags/short_item/889j HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
>

Example curl response

< HTTP/1.1 200 OK
< Date: Wed, 14 Dec 2011 13:30:34 GMT
< Server: Apache/2.2.20 (Ubuntu)
< Content-Length: 230
< Accept-Ranges: bytes
< Vary: User-Agent,Accept-Encoding
< Content-Type: application/json
<
{
	"action": {
		"data": "http://www.example.com/item-0001",
		"type": "url"
	},
	"custom_data": "",
	"description": "Item 0001 Description goes here",
	"id": "item-0001",
	"short_id": "889j",
	"thumbnail": "http://www.example.com/images/new-item.png",
	"title": "Item 0001"
}

POST

Creates a new tag in the system. It will not overwrite an existing tag with the same itemID. If a tag with the same itemID already exists, a "409 Conflict" response will be generated. If you wish to update an existing tag, use the PUT method.

Required Nodes**

  • action: (String) Requires child nodes:
  • type: (String) Currently only "url" is supported
  • data: (String) A well-formed URL

Optional Nodes

  • title: (String) Limit 128 characters
  • description: (String) Limit 1024 characters
  • category: (String) Limit 128 characters
  • show_controls: (Boolean) "true" or "false". Whether to show the TagLabs "Share" button as a Header to your tag in a mobile web view. Depending on subscription levels or acount policy, this may or may not have an effect.
  • thumbnail: (URL) Limit 1024 characters
  • custom_data: (String) Arbitrary data payload that will be preserved as-is; still needs to be JSON-encoded; limit 10K

Example Item ID curl request

curl -v -X POST \
		-H "X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648" \
		-H "Content-Type: application/json" \
		--data-binary @- \
		"https://api.taglabsinc.com/tags/item/item-0002" \
<<EOF
{
   "title": "Title item-0002",
   "description": "Description item-0002",
   "category": "foo",
   "thumbnail": "http://www.example.com/images/new-item.png",
   "custom_data": "",
   "action": {
	   "type": "url",
	   "data": "http://www.example.com/item-0002"
   }
}
EOF

> POST /tags/item/item-0002 HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
> Content-Length: 244
> Content-Type: application/json
>

Example curl response

< HTTP/1.1 201 Created
< Date: Wed, 14 Dec 2011 06:42:27 GMT
< Server: Apache/2.2.20 (Ubuntu)
< Content-Length: 236
Location: /tags/item/item-0002
< Accept-Ranges: bytes
< Vary: User-Agent,Accept-Encoding
< Content-Type: application/json
<
{
	"action": {
		"data": "http://www.example.com/item-0002",
		"type": "url"
	},
	"custom_data": "",
	"description": "Description item-0002",
	"id": "item-0002",
	"short_id": "f2qc",
	"thumbnail": "http://www.example.com/images/new-item.png",
	"title": "Title item-0002"
}

PUT

Updates an existing tag. If the tag does not exist, a new tag is created based on the supplied data.

Required Nodes

  • action: (String) Requires child nodes:
  • type: (String) Currently only "url" is supported
  • data: (String) A well-formed URL

Optional Nodes

  • title: (String) Limit 128 characters
  • description: (String) Limit 1024 characters
  • category: (String) Limit 128 characters
  • show_controls: (Boolean) "true" or "false". Whether to show the TagLabs "Share" button as a Header to your tag in a mobile web view. Depending on subscription levels or acount policy, this may or may not have an effect.
  • thumbnail: (URL) Limit 1024 characters
  • custom_data: (String) Arbitrary data payload that will be preserved as-is; still needs to be JSON-encoded; limit 10K You need to send all the data you wish to preserve for any optional nodes. Not sending optional nodes will result in empty strings being stored instead.

Example Item ID curl request

curl -v -X PUT \
		-H "X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648" \
		-H "Content-Type: application/json" \
		--data-binary @- \
		"https://api.taglabsinc.com/tags/item/item-0002" \
<<EOF
{
   "title": "Title item-0002",
   "description": "Description item-0002 Updated",
   "category": "foo",
   "custom_data": "",
   "thumbnail": "http://www.example.com/images/item-0002-updated.png",
   "action": {
	   "type": "url",
	   "data": "http://www.example.com/item-0002-updated"
   }
}
EOF

> PUT /tags/item/item-0003 HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
> Content-Length: 310
> Content-Type: application/json
>

Example Short Item ID curl request

curl -v -X PUT \
		-H "X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648" \
		-H "Content-Type: application/json" \
		--data-binary @- \
		"https://api.taglabsinc.com/tags/short_item/889j" \
<<EOF
{
   "title": "Title item-0002",
   "description": "Description item-0002 Updated",
   "category": "foo",
   "custom_data": "",
   "thumbnail": "http://www.example.com/images/item-0002-updated.png",
   "action": {
	   "type": "url",
	   "data": "http://www.example.com/item-0002-updated"
   }
}
EOF

> PUT /tags/short_item/889j HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
> Content-Length: 310
> Content-Type: application/json
>

Example curl response

< HTTP/1.1 200 OK
< Date: Wed, 14 Dec 2011 12:23:17 GMT
< Server: Apache/2.2.20 (Ubuntu)
< Content-Length: 303
< Accept-Ranges: bytes
< Vary: User-Agent,Accept-Encoding
< Content-Type: application/json
<
{
	"action": {
		"data": "http://www.example.com/item-0002-updated",
		"type": "url"
	},
	"custom_data": "",
	"description": "Description item-0002 Updated",
	"id": "item-0002",
	"short_id": "csfn",
	"thumbnail": "http://www.example.com/images/item-0002-updated.png",
	"title": "Title item-0002"
}

DELETE

Deletes an existing tag.

CAUTION! If you delete a tag that is in use, there is no way to recreate this tag with the same Short ID! The end result is that you may have a QR code that is available to your customers that no longer works. Please use this method with extreme caution!

Example Item ID curl request

curl -v -X DELETE  \
		-H "X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648" \
		"https://api.taglabsinc.com/tags/item/item-0003"

> DELETE /tags/item/item-0003 HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
>

Example Short Item ID curl request

curl -v -X DELETE  \
		-H "X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648" \
		"https://api.taglabsinc.com/tags/short_item/ab12"

> DELETE /tags/short_item/ab12 HTTP/1.1
> User-Agent: curl/7.21.6 (x86_64-pc-linux-gnu) libcurl/7.21.6 OpenSSL/1.0.0e zlib/1.2.3.4 libidn/1.22 librtmp/2.3
> Host: api.taglabs
> Accept: */*
> X-ActiveTag-AccessToken: 16cc9f55-8c34-433e-af7a-0054884f7648
>
Example curl response
< HTTP/1.1 204 No Content
< Date: Wed, 14 Dec 2011 13:05:13 GMT
< Server: Apache/2.2.20 (Ubuntu)
< Content-Length: 0
< Vary: User-Agent,Accept-Encoding
< Content-Type: application/json
<
Add a custom footer
Add a custom sidebar

Clone this wiki locally