As interacting with items usually means, dealing with a lot of data, the REST Interface for items is a little more complicated, than the other REST endpoints. In the following chapter you will learn about the basic item interactions. To be able to show more complex interactions with the REST API all following examples will be Ruby Script examples
To iteratate over a large number of items, the REST-API offers a curor, that needs to be passed to the API to receive the next chunk of items. The following code snippet shows how to iterate over all of your items and print the GTIN of each item in the console:
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items')
Net::HTTP.start(uri.host, uri.port,
:use_ssl => uri.scheme == 'https') do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
stop = false;
count = 0;
while (!stop) do
response = http.request request # Net::HTTPResponse object
cursor = response['x-item-cursor']
stop = cursor.nil?
request['x-item-cursor'] = cursor
items = JSON.parse(response.body)
items.each do | item |
puts item['primaryKey__']
end
count += items.length
end
puts "Total #{count}"
end
This snippet shows how to work with a cursor, and how to parse the delivered item data into a Ruby Hash. The cursor for fetching the next chunk of items is passed in the response header field x-item-cursor . If there are no more items, this header will not be filled. To get the next chunk of items you simply need to pass the value of the cursor into the next request.
For simplicity the following examples do not use the cursor technique, but will only print the first 20 results. To get all results of your searches you can of course use the cursor technique as described above:
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items?compliant=true')
Net::HTTP.start(uri.host, uri.port,
:use_ssl => uri.scheme == 'https') do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
response = http.request request # Net::HTTPResponse object
items = JSON.parse(response.body)
items.each do | item |
puts item['primaryKey__']
end
end
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items?keyword=Butter')
Net::HTTP.start(uri.host, uri.port,
:use_ssl => uri.scheme == 'https') do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
response = http.request request # Net::HTTPResponse object
items = JSON.parse(response.body)
items.each do | item |
puts item['primaryKey__']
end
end
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items? keyword=gln:4004641000005')
Net::HTTP.start(uri.host, uri.port,
:use_ssl => uri.scheme == 'https') do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
response = http.request request # Net::HTTPResponse object
items = JSON.parse(response.body)
items.each do | item |
puts item['primaryKey__']
end
end
to load an item by its primary key you can just append the primary key to the items url. In contrast to the methods described before, the response contains only a single object. When no items is found, the system returns the HTTP Code 404.
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items/123456789')
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
response = http.request request # Net::HTTPResponse object
item = JSON.parse(response.body)
puts item
end
In order to update existing item properties, you have two basic options:
This example shows the source code for first loading an existing item, and then saving it back to the datastore. By adding the query parameter merge=false it is possible to delete certain values. The default value for merge is true, so by default the passed properties are merged into the existing object. (see next example)
require 'net/http'
require 'json'
uri = URI('https://app.byrd.io/api/v1/items/123456789')
Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http|
request = Net::HTTP::Get.new uri.request_uri
request.basic_auth 'username', 'password'
response = http.request request
item = JSON.parse(response.body)
puts item
item['functionalName'] = "I'm the new name!"
item.delete('shortDescription')
post_uri = URI('https://app.byrd.io/api/v1/items?merge=false')
post_request = Net::HTTP::Post.new('/api/v1/items?merge=false')
post_request.body = JSON.generate(item)
post_request.basic_auth 'username', 'password'
res = Net::HTTP.start(post_uri.hostname, post_uri.port, :use_ssl => true ) do |http|
http.request(post_request)
end
end
As described above, the default behaviour of the POST request, is to merge properties into the existing item. As a consequence it is often not neccessary to load the existing item, before changing its value. The following example shows how to change the functionalName of an item with primary key 123456789:
require 'net/http'
require 'json'
item = Hash.new
item['primaryKey__'] = '123456789'
item['functionalName'] = "I'm the even newer name!"
post_uri = URI('https://app.byrd.io/api/v1/items')
post_request = Net::HTTP::Post.new(post_uri.path)
post_request.body = JSON.generate(item)
post_request.basic_auth 'username', 'password'
res = Net::HTTP.start(post_uri.hostname, post_uri.port, :use_ssl => true ) do |http|
http.request(post_request)
end
IMPORTANT: As all actions are additive, when merging the data, it is not possible to delete values from the item, with this technique