gs1 data store api · pdf filecameron green senior director, b2c, industry solutions, gs1...

GS1 Cloud Phase 1 - Data Store API

Release 0.8.3, DRAFT, December 9, 2017


Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL of 33

Release 0.8.3, DRAFT, December 9, 2017

Document Item Current Value

Document Name GS1 Cloud Phase 1 - Data Store API

Document Date December 9, 2017

Document Version 0.8.3

Document Issue 1

Document Status DRAFT

Document Description GS1 Cloud Phase 1 Data Store API

Contributors

Name Organisation

Dipan Anarkat Technical Product Director, GS1 Cloud, GS1

Ryan Mastrolia Application Engineer, GS1 Cloud, GS1

Mike Wehrs Head of Data Products and Services, GS1

Cameron Green Senior Director, B2C, Industry Solutions, GS1

Birgit Mahler Product Manager, GS1 Cloud, GS1

Ryan Sasser Consultant, GS1

Chris Maki Consultant, GS1

Andy Littman Consultant, GS1

Sean MacGuire Consultant, GS1

Log of Changes

Version Date of Change Changed By Summary of Change

0.1 6 May 2017 Dipan Anarkat Initial draft

0.2 10 May 2017 Dipan Anarkat Support core use cases

0.3 12 May 2017 Dipan Anarkat Large organization use case – Added API for Bulk download of products.

Document rearranged.

0.4 14 May 2017 Dipan Anarkat Modified Bulk upload operations

0.5 14 May 2017 Dipan Anarkat Fixed document navigation and indexing errors

0.6 18 May 2017 Dipan Anarkat Updated APIs and data structure, Security considerations and added examples.

Added the normative API specification in Swagger




0.7 10 July 2017 Dipan Anarkat API specification general clean-up and added new content and APIs. Major changes include the following;

Updated references section

Added API design principles

Updated API security specification to HTTP Basic Authentication

Modified details of request URL structure and included base URL for API access

Added new HTTP headers for HTTP Basic Authentication

Added new AUTHENTICATION_EXCEPTION for an

Exception response.

Added new codes for Status.status

Updated Data Retrieval APIs to enable support for multiple target markets for the same GTIN.

Added new API ‘Get All Products’

Added new API ‘Batch Delete Products’

Updated rules for batch processing of products

Removed the Swagger 2.0 specification

0.7.1 10 July 2017 Dipan Anarkat Corrected error in Status object. Changed code 3 to “Product record refreshed”

0.7.2 10 July 2017 Dipan Anarkat Corrected request URL for API. Added

reason[].path and reason[].errorMessage

parameters to Status

0.7.3 11-July-2017 Dipan Anarkat Errata fix for basePath for request URL,

changed to ‘gs1-pds’ from ‘gs1-portal’.

Removed ‘select={principal}’ filter for ‘Get

All Products’ API and improved API description.

Added new APIs – ‘Get Product Timestamp’ and ‘Refresh Product’.

Updated Disclaimer.

0.7.4 13-July-2017 Dipan Anarkat Renamed ‘Search Products’ API to ‘Search Products by GTIN and Target Market’

Clarified response when no products found for ‘Search Products by GTIN and Target Market’ and ‘Get All Products’ APIs.

Added more detailed data definitions and basic

data validations for attributes of Product

Added ‘required/optional’ for properties of

Product, Exception and Status

Updated references for [ISO639], [ISO3166] and added new reference for GS1 Product Image Specification Standard [GS1PISS]

Corrections made to example for ‘Bulk Upload Products’ API, to denote Target Market as a 3 digit numeric code for country as per [ISO3166]

Updated data definition of targetMarket

defining the support level for all three formats for ISO-3166-1.

Updates to Introduction

0.7.5 14-July-2017 Dipan Anarkat Included new HTTP status code 501 and

NOT_IMPLEMENTED_EXCEPTION, returned for

APIs not implemented yet.




0.8

15-July-2017 Dipan Anarkat Updated sample data for ‘Bulk Upload Products’ API example to genericize them.

Updated data definitions for Product to denote

that gtin and targetMarket are primary keys

in the product database.

General clean-up of the document. DRAFT 0.8 finalized for July 17, 2017 limited release of GS1 Cloud phase 1 application.

0.8.1

12-October-2017 Ryan Sasser Updated /product endpoints to /products

Added ‘Not yet implemented’ to methods that are currently NOT live in staging and / or production environments

0.8.2 28-October-2017 Ryan Sasser

Chris Maki

Andy Littman

Dipan Anarkat

Added /refresh to ‘Refresh Product’ endpoint.

Updated endpoint for ‘Search Products by GPC and target Market’ to /products/{gpc}/{targetMarket}

Removed references to GS1 Product Image Specification Standard and updated guidance on image quality desired in GS1 Cloud, in the

attribute definition for imageUrlMedium

Updated guidance for populating attribute labelDescription

Clarified delete behaviour on non-existent products for ‘Delete Product’ and ‘Batch Delete’.

Improved overview in ‘Data Input API’ and ‘Data Retrieval API’ sub sections.

Updated ‘Batch processing of products’ to support bulk refresh products capability.

Added link to GS1 Cloud MO Zone site in ‘Introduction’.




0.8.3 09-Dec-2017 Ryan Sasser

Dipan Anarkat

Removed `Not Yet Implemented’ on ‘Query Product Information’ and ‘Get All Products’ data retrieval endpoints.

Removed `Not Yet Implemented’ from ‘Get Product Timestamp’ endpoint.

Renamed existing ‘Batch Delete Products’ to ‘Bulk Delete Products’.

‘Bulk Delete Products’ and ‘Bulk Update Products’ are now deprecated, and will be deleted in future version 0.9.0 of the API specification

Section ‘Batch processing of Products’ now deleted, and rules moved to ‘Bulk Update Products’.

Added new section ‘Batch Processing’ to describe API rules for batch methods.

Added new /batch endpoints – ‘Batch Add

Products’, ‘Batch Edit Products’, ‘Batch Modify Products’, ‘Batch Delete Products’ & ‘Batch Refresh Products’.

Added examples for new batch operations.

Added status code 9 (Key is unknown).

Removed /validate endpoint. API method no

longer needed as ‘Validate Product’ use case is supported by ‘Query Product Information’

Added new section to ‘API design’ on ‘Pagination’.

Added information to relevant API methods regarding the HAL spec for paginated responses.

Added new restricted internal use attribute

dataSourceGln to Product.

Implemented pagination for ‘Search by GPC and Target Market’ and ‘Get All Products’ API methods.

Deleted table on Product attribute mapping to

API methods, which now return a full Product

structure.

Updated ‘Authenticate Key’ API with details for status codes returned.

Separated /products/{gtin}/{targetMarket} into two

distinct endpoints with different response

payloads.

Corrected the Search by GPC and Target Market endpoint.

Clarified behaviour of Last-Modified header

for refresh endpoints.

Disclaimer

THIS DOCUMENT IS PROVIDED “AS IS” WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY

OF MERCHANTABILITY, NONINFRINGMENT, FITNESS FOR PARTICULAR PURPOSE, OR ANY WARRANTY OTHER WISE ARISING OUT OF THIS SPECIFICATION. GS1 disclaims all liability for any damages arising from use or misuse of this Specification, whether special, indirect, consequential, or compensatory damages, and including



liability for infringement of any intellectual property rights, relating to use of information in or reliance upon this document.

GS1 retains the right to make changes to this document at any time, without notice. GS1 makes no warranty for the use of this document and assumes no responsibility for any errors which may appear in the document,

nor does it make a commitment to update the information contained herein. GS1 and the GS1 logo are registered trademarks of GS1 AISBL.



Table of Contents

1 Introduction ................................................................................................. 8

1.1 References ..................................................................................................................... 8 1.2 Terms and Definitions ...................................................................................................... 9

2 API Framework ............................................................................................. 9

2.1 API Design Principles ....................................................................................................... 9 2.2 Security ....................................................................................................................... 10 2.3 Versioning of Rest Interfaces .......................................................................................... 10 2.4 Request ....................................................................................................................... 10 2.5 File Types..................................................................................................................... 11 2.6 HTTP Headers ............................................................................................................... 11 2.7 Response ..................................................................................................................... 12 2.8 Pagination .................................................................................................................... 13 2.9 Batch Processing ........................................................................................................... 13

3 Data Definitions .......................................................................................... 13 3.1 Common ...................................................................................................................... 13 3.2 Product ........................................................................................................................ 14 3.3 Status ......................................................................................................................... 16 3.4 Exception ..................................................................................................................... 16

4 API Reference ............................................................................................. 18 4.1 Data Retrieval API ......................................................................................................... 18

4.1.1 Query Product Information ..................................................................................... 19 4.1.2 Query Product Information by Target Market ............................................................ 19 4.1.3 Authenticate Key .................................................................................................. 19 4.1.4 Search Products by GPC and Target Market .............................................................. 20 4.1.5 Download Products Database ................................................................................. 21 4.1.6 Get All Products .................................................................................................... 21 4.1.7 Get Product Timestamp ......................................................................................... 23

4.2 Data Input API .............................................................................................................. 23 4.2.1 Add Product ......................................................................................................... 24 4.2.2 Modify Product ..................................................................................................... 25 4.2.3 Edit Product ......................................................................................................... 25 4.2.4 Delete Product ...................................................................................................... 25 4.2.5 Refresh Product .................................................................................................... 26 4.2.6 Bulk Upload Products (Old Endpoint – DEPRECATED) ................................................. 26 4.2.7 Bulk Delete Products (Old Endpoint - DEPRECATED) .................................................. 28 4.2.8 File Upload Products .............................................................................................. 28 4.2.9 Batch Add Products ............................................................................................... 29 4.2.10 Batch Modify Products ........................................................................................... 30 4.2.11 Batch Delete Products ........................................................................................... 31 4.2.12 Batch Refresh Products .......................................................................................... 32

4.3 Open API Specification ................................................................................................... 33



1 Introduction

The purpose of this document is to outline a specification for the GS1 Cloud Data Store API.

This API enables managing and querying of product data in the GS1 Cloud Data Store. It defines the data and interfaces by which;

Brand owners, retailers and other trading partners of brand owners who originate the data to manage product data into the GS1 Cloud Data Store.

Internet Application Providers (IAPs), consumers and businesses to query and search

for product data. It supports the three core use cases for GS1 Cloud Phase 1;

i. CHECK (Key Authentication)

ii. VIEW (Product Validation)

iii. EXPLORE (Search Function)

Future phases of this project may provide additional capabilities in the Data Store API to better manage, query and search product data using the GS1 Cloud Phase 1 application. Although the

specification is full featured, not all APIs are immediately available for consumption. Only select APIs will be released initially and implementation for additional APIs will follow thereafter. For details on the release schedule for APIs, please check the GS1 Cloud User Guide document and additional information on the GS1 Cloud websites at;

http://mozone.gs1.org/gs1-cloud/

https://www.gs1.org/gs1-cloud

1.1 References

Normative references:

■ [GS1GS] GS1, “GS1 General Specifications”, https://www.gs1.org/barcodes-epcrfid-id-keys/gs1-general-specifications.

■ [ISO3166] “Codes for the representation of names of countries and their subdivisions – Part 1: Country codes,” ISO 3166-1:2013. https://www.iso.org/publication/PUB500001.html

■ [ISO639] “Codes for the representation of names of languages -- Part 1: Alpha-2 code,” ISO 639-1:2002. http://www.loc.gov/standards/iso639-2/php/code_list.php

■ [HTTP] IETF, “Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing,” IETF RFC 7230, June 2014, http://www.ietf.org/rfc/rfc7230.txt.

■ [ISODir2] ISO/IEC Directives part 2; Rules for the structure and drafting of International Standards – 6th edition, 2011.

■ [RFC2246] T. Dierks, C. Allen, “The TLS Protocol, Version 1.0,” RFC2246, January 1999,

http://www.ietf.org/rfc/rfc2246.

■ [RFC2818] E. Escorla, c/rfc2246“The TLS Protocol, Version http://www.ietf.org/rfc/rfc2818.

■ [RFC3268] P. Chown, “Advanced Encryption Standard (AES) Ciphersuites for Transport Layer Security (TLS),” RFC3268, June 2002, http://www.ietf.org/rfc/rfc3268.

■ [RFC3986] T. Berners-Lee, R. Fielding, L. Masinter, “Uniform Resource Identifier” (URI): Generic Syntax,” RFC3986, January 2005, http://www.ietf.org/rfc/rfc3986.

■ [JSON] ECMA International, “The JSON Data Standard Interchange Format, 1st Edition,” ECMA Standard ECMA-404, October 2013, http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

■ [HAL] Kelly, Mike “HAL – Hypertext Application Language A lean hypermedia type” June 13, 2013, http://stateless.co/hal_specification.html

http://mozone.gs1.org/gs1-cloud/



https://www.gs1.org/barcodes-epcrfid-id-keys/gs1-general-specifications

https://www.gs1.org/barcodes-epcrfid-id-keys/gs1-general-specifications

https://www.iso.org/publication/PUB500001.html

http://www.loc.gov/standards/iso639-2/php/code_list.php

http://www.ietf.org/rfc/rfc7230.txt

http://www.ietf.org/rfc/rfc2246

http://www.ietf.org/rfc/rfc2818

http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

http://stateless.co/hal_specification.html



1.2 Terms and Definitions

Within this specification, the terms SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, NEED NOT, CAN, and CANNOT are to be interpreted as specified in Annex G of the ISO/IEC Directives, Part 2,

2001, 4th edition [ISODir2]. When used in this way, these terms will always be shown in ALL CAPS; when these words appear in ordinary typeface they are intended to have their ordinary English meaning.

All sections of this document, except for the introduction, are normative, except where explicitly noted as non-normative.

The following typographical conventions are used throughout the document:

■ ALL CAPS type is used for the special terms from [ISODir2] enumerated above.

■ Monospace type is used to denote programming language, UML, and JSON identifiers, as well

as for the text of JSON elements.

Placeholders for changes that need to be made to this document or future capability, prior to its

reaching the final stage of approved GS1 specification are prefixed by a rightward-facing arrowhead, as this paragraph is.

2 API Framework

This section overviews the ‘Data Store API’ implementation using REST principles. The specifics of this API design are specified in sub sections below and detailed method implementations for the API are specified further below in the sections to follow.

2.1 API Design Principles

This API is modelled as resource-oriented API with collections of individually addressable resources

(the nouns of the API). Resources are referenced with their resource names and manipulated via a small set of methods (also known as verbs or operations). The API is modeled as a resource hierarchy, where each node is either a simple resource or a collection resource. For convenience, they are often called as a resource and a collection, respectively.

■ A resource has some state and zero or more sub-resources. Each sub-resource can be either a simple resource or a collection resource.

■ A collection contains a list of resources of the same type.

■ Where the desired API functionality does not map to resources and methods, custom methods are used.

■ This API currently addresses a simple resource Product and the corresponding collection

resource Product[].

This REST style for this API is characterized by:

■ HTTP is used as the transport protocol.

■ The request is constructed using the HTTP request method suited for that operation (GET, POST, DELETE, PATCH, PUT, etc.)

■ The response payload is a JSON response document

■ HTTP response code 200 indicates success. HTTP response codes not beginning with “2” are used to indicate exceptions.

Users of the GS1 Cloud Phase 1 application SHALL make a HTTP request to the GS1 Cloud Data Store who SHALL respond using JSON formatted data. Both the client and service SHALL conform to HTTP 1.1 [HTTP].



2.2 Security

To support interim deployment of the GS1 Cloud application, the security scheme used will be HTTP Basic Authentication over TLS. HTTP basic authentication is a simple challenge and response

mechanism with which a server can request authentication information (a userid and password)

from a client. The client passes the authentication information to the server in an HTTP

Authorization header. The authentication information is in base-64 encoding. The format of the

Authorization header is:

Authorization: Basic userid:password

The HTTP Basic authentication scheme SHALL be secured using SSL encryption to protect the

userid and password. As such, all API access SHALL be made over HTTPS.

The email-id for the user account and the corresponding API Key SHALL be used as userid and

password with HTTP basic authentication for client authorization and authentication. The challenge

token to be used is derived by concatenation of ‘email-ID:API Key’ and then encoding it in base-64.

Prior to using the ‘Data Store API’ exposed by the GS1 Cloud Data Store, users of the service SHALL have established a trust relationship with GS1 for the user of the GS1 Cloud service by creating a user account on the GS1 Cloud portal. Each user will get a unique system generated API Key accessible in the user account information on the portal.

A comprehensive proposal for security, authorization and authentication will be provided at a later stage pending a complete architecture and security review of the GS1 Cloud system, to include requirements for API gateway management. Possible options for the future include;

■ Server-to-client authentication be done via TLS server-side certificates, with certificates of client users registered with GS1.

■ For client-to-server authentication, a combination of variety of approaches may be used, including;

□ a MAC code in the HTTP query or an HTTP header in the query containing a MAC

□ an API Key

□ an OAuth 2.0 security token

Mac code generation specification may be defined in the future and will be based on Amazon style HMAC or similar.

2.3 Versioning of Rest Interfaces

The REST interfaces for the ‘Data Store API’ use the following mechanisms to provide versioning for the request URL:

■ Compatible Change: New operations and new query parameters may be added to a REST interface by a new version of this specification. The base Service URL and service URL version number remains the same.

■ Incompatible Change: A REST interface may be changed incompatibly by updating the version string embedded in the request URL. During a period of transition, both the old and new URLs may be implemented simultaneously.

2.4 Request

A client SHALL implement each API method by formulating an HTTP request as specified in this

section. A client SHALL make a RESTful HTTP request as specified in this section

The HTTP URL for the request SHALL have the following form:

Scheme://Host/BasePath/v1/EndPoint/Resource/Action?Parameters

where:

■ Scheme SHALL be https.

■ Host is the host (name or IP) of the server serving the API, for the GS1 Cloud Phase 1 Application.



■ BasePath is the base path on which the API is served, which is relative to the host.

■ The two characters v1 denote that the operation being invoked is as specified in this version of

the ‘Data Store API’ specification. These characters are reserved to provide for a staged transition to an incompatible version of the API specification in the future.

■ The EndPoint denotes the actual service end point for this RESTful API.

■ Resource is a URL path segment as specified according to the interface operation to be invoked

by this request and the subject of that operation. For collection resources, the Resource path

may be skipped or provided as URL parameters.

■ Action is a URL path segment and specifies the operation to be invoked on the Resource. It is

an action verb and used when the operation desired does not naturally map to the HTTP method

invoked. This may be skipped if not needed.

■ Parameters is an HTTP query string encoding parameters for the request beyond those encoded

into Resource.

The HTTP method SHALL be one of the following GET, POST, PUT, PATCH , HEAD or DELETE and the

HTTP request payload shall be as defined in section 4 “API Reference” below.

For version 1 of this API, the following values are applied;

HTTP URL Path Value

Host PRODUCTION server: cloud.gs1.org

STAGING (TEST) server: cloud.stg.gs1.org

BasePath gs1-pds/api

As such, the base HTTP URLs for this API SHALL be as follows;

Environment Request URL (API)

PRODUCTION https://cloud.gs1.org/gs1-pds/api/v1

STAGING (TEST) https://cloud.stg.gs1.org/gs1-pds/api/v1

2.5 File Types

The following file types are supported by the system for bulk operations – both upload and

download;

File Type File Extension

MIME Type for HTTP Headers

Microsoft Excel Open Excel format

.xlsx application/vnd.openxmlformats-

officedocument.spreadsheetml.sheet

JavaScript Object Notation .json text/plain

For file operations, the JSON file is uploaded as a text file but SHALL be processed as a JSON formatted file.

■ Maximum file size for uploads is limited to 100 MB

■ Maximum file size for downloads is limited to 2GB

Editor’s note: Need to describe MIME Type for CSV file support in the future

2.6 HTTP Headers

The HTTP request and response will include the following entity headers as specified below;



Header Header Type

Value

Content-Type

Entity The value for media/MIME type in the header ‘Content-Type’ HTTP entity

header SHALL be set to ‘application/json’ for all HTTP request – response

operations where a JSON object is passed in the HTTP response body.

If the request or response contains a file, the media/MIME type SHALL be set corresponding to the file type as specified in the section above.

Accept Entity If the request expects a particular file type, the media/MIME type SHALL be set corresponding to the file type as specified in the section above.

Content-Length

Content-MD5

Content-Encoding

Entity If the request or response contains a file then these headers SHALL be set appropriately.

Cache-Control

Content-Location

Expires

Last-Modified

Entity If the response contains a file then all these headers SHALL be set appropriately.

The Last-Modified header SHALL be returned for all API calls that query or

update the last updated timestamp for the given product record.

Authorization

WWW-Authenticate

Entity Every request SHALL include the Authorization header. Upon authentication

error, the server will include the WWW-Authenticate header as specified below

to indicate that HTTP Basic Authentication security scheme is used. WWW-Authenticate: Basic realm="GS1 Cloud"

2.7 Response

The ‘Data Store API’ service SHALL respond to an HTTP request as specified in this section. An authorized user acting as a ‘Data Store API’ client SHALL interpret an HTTP response as specified in this section.

The ‘Data Store API’ SHALL process an incoming HTTP request as follows:

■ If the HTTP URL matches the base URL and resource portion of the URL as specified in section 4 “API Reference” below, then:

□ If the request is authenticated for the security scheme specified, then;

If the HTTP method matches the HTTP method specified in Section ‘API Reference’ for the operation named in the URL, then process the request as specified below.

Otherwise, the HTTP method is inappropriate: respond with HTTP error code 405, with

no HTTP response payload

□ Otherwise, authentication has failed: respond with HTTP error code 401 for unauthorized

access and the WWW-Authenticate header is set.

■ Otherwise, the request is outside the scope of this specification, and the response is server dependant will be an appropriate HTTP error code. If the request is considered invalid by the

implementation, the implementation SHALL respond with HTTP error code 400 or 404.

■ Although the API specification document provides a detailed specification for the GS1 Cloud Data Store, not all APIs maybe available. The GS1 Cloud User Guide will provide the latest and most accurate information on the availability and support for APIs contained in this specification. Requests made for APIs that may not have been implemented by the service SHALL get a response

with HTTP error code 501.

The following table also specifies the HTTP response code for each outcome:

Outcome HTTP response code Response

SUCCESS 200 Operation successful.

NO_DATA_EXCEPTION 404 exception data object returned with code set to “1”

INVALID_REQUEST_EXCEPTION 400 exception data object returned with code set to “2”



Outcome HTTP response code Response

IMPROPER_REQUEST_EXCEPTION 400 exception data object returned with code set to “3”

SECURITY_EXCEPTION 403 exception data object returned with code set to “4”

IMPLEMENTATION_EXCEPTION 500 exception data object returned with code set to “5”

AUTHENTICATION_EXCEPTION 401 exception data object returned with code set to “6”

NOT_IMPLEMENTED_EXCEPTION 501 exception data object returned with code set to “7”

When an Exception occurs the Response payload SHALL contain an Exception[] with the

appropriate details. Also, see section 3.4 “Exception” below or more details on formatting the response payload with details about the exception.

2.8 Pagination

Some API methods provide a paginated response. Pagination is implemented using a combination of query parameters and response attributes.

API responses are capped at a maximum of 1000 products. Where noted responses are paginated

via the Hypertext Application Language standard [HAL]. A HAL response is standard JSON, with a

defined structure. For all paginated responses, the product array (Product[]) will be present in the

“_embedded” portion of the response. Metadata about previous, next, first, and last pages are also

provided. Clients can provide query parameters to a paginated URL to request a specific page number and page size (maximum of 1000 records).

The following table provides the list of query parameters included in the HTTP URL to control pagination;

Parameter Value / Type

Description

page={pageNumber} integer pageNumber is a zero indexed integer representing the page of data

requested. If not provided, or a negative value is sent, it will default to 0. Page numbers

size={pageSize}

integer size is an integer from 1 to 1000. If not provided it will default to

1000, if less than 1 it will default to 20.

2.9 Batch Processing

For performance and security reasons, only 1000 product records can be included in a single API call with the all batch methods;

If there are more records than the specified limit, then a SECURITY_EXCEPTION is raised. See section

3.4 Exception below for more details for raising an Exception.

3 Data Definitions

3.1 Common

Property Name Value / Type

Description

gtin string The GTIN represents a Global Trade Item Number (GTIN). The GTIN type is a 14-character numeric string which may contain a GTIN-8, GTIN-12, GTIN-13, or GTIN-14 as defined in the GS1 General Specifications [GS1GS]. When the GTIN type holds a GTIN-8, GTIN-12, or GTIN-13, the GTIN value is padded on the left with zeros to make 14 characters total, as illustrated in [GS1GS, Section 3.3.2].




Description

targetMarket string Target market for the product, by default expressed as a 3-character numeric string that identifies a country, using the 3- digit country codes defined by ISO 3166-1 numeric [ISO3166].

Although, the GS1 Cloud service can process all three ISO3166-1 numeric, alpha-2 and alpha-3 formats, it is recommended that clients adhere to the numeric format, which is the default format for the service.

If a targetMarket is provided in a particular format, the server

response returned will be in the same format. For API calls that do not

have targetMarket as a query parameter, the server response will

always be in the default server format of ISO-3166-1 numeric.

Product Object Product data resource transacted with the GS1 Cloud Phase 1 service.

Status Object The result of processing a request.

Exception Object An exception result as the result of processing a request.

3.2 Product

The following table specifies the properties for Product: (PK indicates Primary key in the product

database)


Required/Optional Description

gtin string Required (PK) GTIN of the product.

targetMarket string Required (PK) Target market for the product.

brand string Optional The brand of the product, as printed on the

package. Normally, the brand most recognizable by the consumer, but as determined by the brand owner.

This is the most common name used to describe uniquely and identify a line of trade item or services to consumers of the Trade Item on its packaging.

The Brand Name has a length of 1-70 characters.

Note: The Brand name may not be the largest brand text or trade item name/description on the package. Marketing or package designers determine how names and descriptions are listed on the package. It may be determined that the size of a brand name should be small to fit into the artistic or aesthetic design for the package.





labelDescription string Optional Description of the product as printed on the

product label. This is a literal reproduction of the text featured on a product’s label.

The Label Description has a length of 1-500 characters.

For data sourced from GDSN;

1. If available, use Label Description.

2. If not, then use Trade Item Description.

3. If neither exist, attribute is not populated with any value.

For data sourced from non-GDSN sources, if the data field is synonymous with the definition of Label Description or Trade Item Description, use it as per guidance above for GDSN. If not, then populate whatever best product description maybe available in the source system. If there’s no match then then the attribute is not populated.

companyName string Optional The organization that owns the brand regardless

of where and by whom it is manufactured and who is normally responsible for the allocation of

the gtin.

The Company Name has a length of 1-200 characters.

gpc string Optional Global Product Classification (GPC) code required

to classify the product. The 8-digit Global Product Classification (GPC) for the product, down to the level of the “brick”. This data can be a key criterion in any search of the GS1 Cloud data.

imageUrlMedium string Optional URL string that refers to a resource on the

internet, usually consisting of the protocol http or

https, followed by the domain name and path.

This field represents the resource (web location) that includes a basic product image to be shown.

In short, it is a publicly accessible web URL of an image of the product. This URL should be for a medium sized image (JPG, PNG, etc.), not for a web page (HTML).

The Medium Resolution Image URL has a length of 1-2500 characters.

Image SHOULD NOT exceed 600 Kb in file size and must be at least 320 x 240 pixels in resolution. If image matching this guidance is not available then provide URL to the best possible picture for product.

informationProviderGln string Required Global Location Number (GLN) of the party that

owns the product data.

The GLN represents a Global Location Number (GLN). The GLN type is a 13-character numeric string.

languageCode string Required 2-character string that identifies a human

language, using the 2-character language codes defined by ISO 639-1 [ISO639]. Note that both characters of an ISO 639-1 code are lowercase.





dataSourceGln String Restricted Global Location Number (GLN) of the data source

for the product data.

The use of this attribute is restricted and applicable only for internal use with connector data sources in the GS1 Cloud application. i.e.

GS1 Cloud – GDSN connector (Kato); identifies the GDSN Source Data Pool which provided the product data record.

GS1 Cloud – GEPIR connector; identifies the GS1 MO host in the GEPIR network, if the

product data was sourced from GEPIR Item.

This is a required attribute when used by a connector data source.

3.3 Status

The following table specifies the properties for Status:



gtin string Required GTIN of the product

targetMarket string Conditional Target market of the product. Not returned for

GTIN only operations.

status number Required Code identifying the result of the operation

1: Product record created

2: Product record modified

3: Product record refreshed

4: Product record deleted

5: Operation failed

6: Not authorized to perform this operation

7: Key is valid

8: Key is not valid

9: Key is unknown

reason[] Array Optional One or more reasons why the operation failed.

Provided only when status is ‘5’

reason[].path string Optional Context path for the failure

reason[].errorMessage string Required Human readable error message

3.4 Exception

The following table specifies the properties for Exception:



exception integer Required A code number that specifies the type of exception that

occurred. Reference table above for exception code. The value SHALL be one from the Exception codes provided in the table below.





message string Optional A human readable string providing additional information about the exception. This is not intended for presentation to end consumer. The content is at the discretion of the server but SHALL always be in English.

The following table specifies the different types of exceptions that can be raised.

Exception Name Exception Code

Operations Description

NO_DATA_EXCEPTION 1 All Operations No data is available for the gtin and

targetMarket specified in the request

INVALID_REQUEST_EXCEPTION 2 All Operations At least one gtin or targetMarket specified

in the request is not properly formatted, or has an incorrect check digit.

IMPROPER_REQUEST_EXCEPTION 3 All Operations The request was not formatted correctly, contained an unknown parameter, or specified an unknown operation.

SECURITY_EXCEPTION 4 All Operations The operation was not permitted due to an access control violation or other security concern. This includes the case where the service wishes to deny authorization to execute a particular operation based on the authenticated client identity.

IMPLEMENTATION_EXCEPTION 5 All Operations A generic exception thrown by the implementation for reasons those are implementation-specific, such as a software error.

AUTHENTICATION_EXCEPTION 6 All Operations Authentication error or failure for the security scheme specified.

NOT_IMPLEMENTED_EXCEPTION 7 Operations not implemented

Either the server does not recognize the request method, or it lacks the ability to fulfil the request. Usually this implies future availability, i.e. a new feature / method of the API that is documented in the specification but currently not implemented.

If more than one exception applies to a given request, the GS1 Cloud Phase 1 service SHALL respond with the applicable exception that occurs closer to the bottom of the above list; however,

the service MAY choose to respond with INVALID_REQUEST_EXCEPTION in the case that

INVALID_REQUEST_EXCEPTION and SECURITY_EXCPTION both apply.

Also, see section 2.7 “Response” above for full details on the HTTP error codes to be set for the

response.

Response Examples with exception

HTTP/1.1 400 Bad Request

Content-Type: application/json

{"exception":2,"message":"Invalid GTIN provided"}

HTTP/1.1 401 Unauthorized


WWW-Authenticate: Basic realm="GS1 Cloud"

{"exception":6,"message":"Invalid API key"}

HTTP/1.1 403 Forbidden




{"exception":4,"message":"Operation not permitted"}

HTTP/1.1 404 Not Found


{"exception":1,"message":"Missing parameter: Target Market"}

HTTP/1.1 500 Internal Server Error


{"exception":5,"message":"Cannot process request at this time"}

HTTP/1.1 501 Not Implemented


{"exception":7,"message":"Not available at this time"}

4 API Reference

The Data Store API provides the following methods for data retrieval and data input of product information. These are classified accordingly as;

■ Data Retrieval APIs

■ Data Input APIs

The following sub-sections provides the implementation details for these methods.

4.1 Data Retrieval API

Internet Application Providers (IAPs) can use the data retrieval method of Data Store API to build their own applications. Consumers will typically interact with the GS1 Cloud Phase 1 through applications provided by the connected IAPs. Businesses will typically interact with the GS1 Cloud Phase to handle common business use cases that depend on basic product information.

The Data Retrieval APIs also enables a consumer-facing application for accessing publicly-available product data via online or mobile channel. Most importantly, it provides core functionality to support three of the most common use cases enabling online shopping and e-commerce.

1. GTIN Authentication (CHECK): Verify if a specific GTIN is in the GS1 Cloud and therefore the Global Company Prefix (GCP) was licensed properly.

2. Product Validation (VIEW): Allows a requestor to provide a GTIN and get some basic product information about that GTIN that is foundational to e-commerce and consumer in-store product research. Note: Some large companies will want to validate the GTINs they already have and

will need a list of all of GS1 Cloud product records on a nightly basis for this purpose. This functionality is provided by the Query Product Information method (see below).

3. Search Function (EXPLORE): This use case allows a user to have a list of products filtered by their product classification and the target market where they are sold

The following table specifies the data retrieval methods for the ‘Data Store API’:

Method API HTTP Method

Response payload

Query Product Information /products/{gtin}

GET Product[]

Query Product Information by Target Market

/products/{gtin}/{targetMarket} GET Product

Authenticate Key /products/{gtin}/authenticate

Not yet implemented

GET Status




Response payload

Search by GPC and Target Market

/products/gpc/{gpc}/{targetMarket}?page={pag

eNumber}&size={pageSize}

Not Yet Implemented

GET HAL with

Product[]

Download Products Database

/products/db

Not Yet Implemented

GET .XLSX file

format containing Product[]

Get All Products /products?page={pageNumber}&size={pageSize} GET HAL with

Product[]

Get Product Timestamp /products/{gtin}/{targetMarket} HEAD

4.1.1 Query Product Information

GET /product/{gtin}

This API returns the full product record(s) from the Data Store for the GTIN. If multiple GTIN and Target market variations exist, product data records for all applicable target markets will be returned.

HTTP Method GET

Endpoint /products

Resource /{gtin}

Action

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload Product[]

4.1.2 Query Product Information by Target Market

GET /product/{gtin}/{targetMarket}

This API returns the full product record from the Data Store for the given GTIN and Target Market.

HTTP Method GET

Endpoint /products

Resource /{gtin}/{targetMarket}

Action

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload Product

4.1.3 Authenticate Key

GET /product/{gtin}/authenticate



This API returns the status if the provided GTIN was authenticated. It supports the Key Authentication use case allowing a requestor to provide a GTIN and find out if it has been issued by GS1 (valid Company Prefix).

Not yet implemented

IMPORTANT: The detailed definition and rules for the status codes returned (below) is still being discussed and will be finalized in the next revision to the API specification.

HTTP Method GET

Endpoint /product

Resource /{gtin}

Action /authenticate

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload Status with status set to inform result of key verification operation.

If the GTIN exists in GS1 cloud, and its GCP is successfully verified, a status code

of ‘7’ (Key is valid) will be returned.

If the GTIN exists in GS1 cloud, and its GCP is not successfully verified, a status

code of ‘8’ (Key is not valid) will be returned.

If the GTIN does not exist in GS1 Cloud, a status code of ‘9’ (Unknown) will be

returned.

4.1.4 Search Products by GPC and Target Market

GET /products/gpc/{gpc}/{targetMarket}?page={pageNumber}&size={pageSize}

This API allows a user to search the Data Store and have a list of products filtered by their product classification and the target market where they are sold. If no products found matching search

criteria, an empty JSON array [] is returned.

Not yet implemented

URL path for this endpoint is likely to change

HTTP Method GET

Endpoint /products

Resource /gpc/{gpc}/{targetMarket}

Action

Parameters HTTP URL page={pageNumber}

size={pageSize}

See section 2.8 Pagination for details on page and size query parameters.

Parameters Body

Request Payload

Response Payload HAL with Product[]

See section 2.8 Pagination for details on HAL.



4.1.5 Download Products Database

GET /products/db

This API returns an Excel or JSON file capturing the entire database of products in the Data Store.

It supports the use case where some large companies will want to validate the GTINs they already have and will need a list of all of item records available in the GS1 Cloud, on a nightly basis for this

purpose. GS1 will make available a file containing the entire product catalogue in a predetermined format. The file will be system generated every 24 hours, and hosted on a server directory. For security and performance reasons, new files created nightly will have a randomly generated file name and the old file will be deleted. The file is available to authenticated users via machine access using

the API and will also be available in the user account on the GS1 Cloud portal. Accept request header

MUST be set appropriately.

When the API is called, the response body will have the HTTP response header Content-Location set

to the absolute path of the file on the same or different server, which can then be used to get the file.

See section 2.6 “HTTP Headers” above for more details on file types supported and the HTTP request

and response headers that are set.

Not yet implemented

File type should be UTF-8 encoded CSV or similar. Excel file has size limitations on total number of rows with approximately only 1 million rows allowed.

HTTP Method GET

Endpoint /products

Resource

Action /bulk

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload CSV file containing Product[]

4.1.6 Get All Products

GET /products?page={page}&size={pageSize}

This API returns all product data records for the member account only.

A member can have multiple users, each with its own account and unique API key for access to the system. This API returns all product data records for all user accounts for the member company. If

no products found matching search criteria, an empty JSON array [] is returned.

HTTP Method GET

Endpoint /products

Resource

Action

Parameters HTTP URL page={pageNumber}

size={pageSize}

See section 2.8 Pagination for details on page and size query parameters.

Parameters Body



Request Payload

Response Payload HAL with Product[]

See section 2.8 Pagination for details on HAL.

Response Example

HTTP/1.1 200 OK


{

"_embedded" : [ {

"gtin" : "00000065045497",

"targetMarket" : "834",

"brand" : "test brand",

"languageCode" : "en",

"labelDescription" : "description",

"gpc" : "gpc",

"companyName" : "company",

"informationProviderGln" : "1295170330647",

"imageUrlMedium" : "medium image url"

}, {

"gtin" : "00000085059801",





"gpc" : "gpc",




}, {

"gtin" : "00000072418482",





"gpc" : "gpc",




}, {

"gtin" : "00000023607798",





"gpc" : "gpc",




}, {

"gtin" : "00000073739913",





"gpc" : "gpc",




} ],

"page" : {

"size" : 5,

"totalElements" : 4857,

"totalPages" : 972,

"number" : 400

},

"_links" : [ {

"rel" : "first",

"href" : "https://localhost:8443/gs1-pds/api/v1/products?page=0&size=5"

}, {

"rel" : "prev",




}, {

"rel" : "self",


}, {

"rel" : "next",


}, {

"rel" : "last",


} ]

}

A subsequent version of this API may provide the following capabilities;

□ To filter product data records by user and other criteria.

□ To request and receive data in the supported file formats (excel, csv etc.).

4.1.7 Get Product Timestamp

HEAD /product/{gtin}/{targetMarket}

This API returns the last updated date time for the specified product. The timestamp information will

be returned in the Last-Modified response header.

HTTP Method HEAD

Endpoint /product


Action

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload

4.2 Data Input API

Brand Owners will use the data input methods of the Data Store API to maintain their product data. Additionally, these methods provide a simple mechanism for various data providers to upload product data to GS1 Cloud.

■ GDSN connector (Kato): For accepting product data GDSN Data Pools.

■ GEPIR Connector: For transferring product data from GS1 GEPIR.

■ Key Management Connector: For updates either from the Global Key Management System (“GS1 Activate”) or from MOs who have a compatible key management system of their own.

■ File Upload API: For bulk transfers of MO-specific product data catalogues and other bulk sources of product data.

The following table specifies the data input methods for the ‘Data Store API’:


Request payload

Response payload

Add Product /products POST Product

Modify Product /products/{gtin}/{targetMarket} PUT Product

Edit Product /products/{gtin}/{targetMarket} PATCH Product

Delete Product /products/{gtin}/{targetMarket} DELETE




Request payload

Response payload

Refresh Product /products/{gtin}/{targetMarket}/r

efresh PATCH

Bulk Upload Products /products/bulk

Deprecated. Will be removed in draft specification version 0.9.0

POST Product[] Status[]

Bulk Delete Products /products/delete

Deprecated. Will be removed in draft specification version 0.9.0

POST Product[] Status[]

Batch Add Products /products/batch/add POST Product[] Status[]

Batch Modify Products /products/batch/modify POST Product[] Status[]

Batch Delete Products /products/batch/delete POST Product[] Status[]

Batch Refresh Products /products/batch/refresh POST Product[] Status[]

File Upload Products /products/file

Not yet implemented

POST .XLSX file

format containing Product[]

The information populated in Product depends on the action requested. The table below captures

which product attributes are expected by the individual methods. (‘+’ indicates required, ‘?’

indicates optional and ‘r’ indicates restricted use):

Property Name Add Product

Modify Product

Edit Product

Delete Product(s)

Refresh Product

All other operations

gtin x x x x x x

targetMarket x x x x x x

brand x x ? x

labelDescription x x ? x

companyName x x ? x

gpc x x ? x

imageUrlMedium x x ? x

informationProviderGln x x ? x

languageCode x x ? x

dataSourceGln r r r r

4.2.1 Add Product

POST /products

This API adds a single product to the Data Store.

HTTP Method POST

Endpoint /products

Resource

Action

Parameters HTTP URL

Parameters Body



Request Payload Product

Response Payload If the product record already exists, then an Exception is returned containing the

appropriate error information.

4.2.2 Modify Product

PUT /products/{gtin}/{targetMarket}

This API modifies a single product in the Data Store. The entire product information is required. This operation has the effect of completely replacing the Product information for the given GTIN and Target Market.

HTTP Method PUT

Endpoint /products


Action

Parameters HTTP URL

Parameters Body


Response Payload If the product record does not exist or if the user does not have authorization to

modify the product record, then an Exception is returned containing the


4.2.3 Edit Product

PATCH /products/{gtin}/{targetMarket}

This API updates partial product information for a single product in the Data Store. This API is used when only a subset of entire product information is needed to be updated.

HTTP Method PUT

Endpoint /products


Action

Parameters HTTP URL

Parameters Body



modify the product record, then an Exception is returned containing the


4.2.4 Delete Product

DELETE /products/{gtin}/{targetMarket}

This API deletes a single product from the Data Store.

HTTP Method DELETE

Endpoint /products




Action

Parameters HTTP URL

Parameters Body

Request Payload

Response Payload If if the user does not have authorization to delete the product record, then an

Exception is returned containing the appropriate error information. If the product

record does not exist then a HTTP status code of 200 is returned.

4.2.5 Refresh Product

PATCH /products/{gtin}/{targetMarket}/refresh

This API call refreshes the product last updated timestamp in the Data Store with the current time. In effect, it explicitly confirms that the existing product data is fresh. The API returns the last updated date time for the specified product, which is the timestamp when the product was refreshed. The

timestamp information SHALL be returned in the Last-Modified response header.

HTTP Method PATCH

Endpoint /products


Action /refresh

Parameters HTTP URL

Parameters Body

Request Payload


delete the product record, then an Exception is returned containing the


4.2.6 Bulk Upload Products (Old Endpoint – DEPRECATED)

POST /products/bulk

NOTE: This method is deprecated and will be removed in version 0.9.0

This API provides the capability to perform a batch upload to the Data Store, containing multiple

products records in JSON format in the response body. This method can be used to add new products

or modify existing products.

For products uploaded using this method, the server executes the following behaviour. For a given

gtin and targetMarket key combination;

■ All field validations SHALL be performed for each product record. If validation fails, then

Status.status and Status.reason are set accordingly in the response for the given

product record.

■ If the product does not exist, then it is created and Status.status is set accordingly in the

response for the given product record.

■ Otherwise, the product already exists, and a Modify Product or Refresh Product operation is performed for the product record as requested.

o Apply the following authorization rule first; Only members who have added the product record

initially SHALL be allowed to modify it. Check if the user has authorization to edit the product



record. Using the API key to identify the GLN of the member, check for ownership of the product record in consideration.

o If authorization check succeeds, then the requested operation is performed on the product

data records and Status.status is set accordingly in the response for the given product

record. Otherwise Status.reason is also set to indicate the failed operation.

o If only gtin and targetMarket attributes are provided, then a Refresh Product is performed,

otherwise a Modify Product is performed.

HTTP Method POST

Endpoint /products

Resource

Action /bulk

Parameters HTTP URL

Parameters Body

Request Payload Product[]multiple products in JSON

Response Payload Status[] containing the registration or update status of each individual record –

either success or failure of the operation requested.

Request Example

POST /gs1-pds/api/v1/products/bulk HTTP/1.1

Host: cloud.gs1.org


Accept: application/json

Authorization: Basic aHR0cHdhdGNoXcfft54jYtGG7h02TiQzOmY=

[

{

"gtin": 09504000059231,

"targetMarket": "056",

"brand": "GS1",

"labelDescription": "Annual Report 2012/2013",

"companyName": "GS1 Global Office",

"gpc": 10000927,

"imageUrlMedium": "https://www.gs1.org/test.jpg",

"informationProviderGln": 0500000000951,

"languageCode": "en"

},

{

"gtin": "09506000036809",


"labelDescription": "GS1 Test Product 1",

"imageUrlMedium": "www.example.com/test1.jpg"

},

{

"gtin": "09506000036816",

"targetMarket": "040"



},

]

Response Example

HTTP/1.1 200 OK




[

{"gtin":09504000059231,"targetMarket":"056","status":1},

{"gtin":"09506000036809","targetMarket":"840","status":2},

{"gtin":"09506000036816","targetMarket":"040","status":5,"reason":"Operation not

permitted. Not authorized."}

]

4.2.7 Bulk Delete Products (Old Endpoint - DEPRECATED)

POST /products/delete

NOTE: This method is deprecated and will be removed in version 0.9.0

This API provides the capability to request deletion of a batch of products in the Data Store. This method can be used to delete existing products.

HTTP Method POST

Endpoint /products

Resource

Action /delete

Parameters HTTP URL

Parameters Body

Request Payload Product[]multiple products in JSON containing gtin and targetMarket of

product data records to be deleted.

Response Payload Status[] containing the deletion status of each individual record – either success

or failure of the operation requested. Note that if a product does not exist, the system does not consider that to be an error condition and a Status code of 4 will be returned.

4.2.8 File Upload Products

POST /products/file

This API provides the capability to perform a batch upload to the Data Store, containing multiple

products records in a File. This API only performs an upload of the file to the server and returns a status of the file was uploaded. The file is processed asynchronously and updates are made to the Data Store within 24 hours. Once processed, the status of processing the file is available in the user account. The maximum file size supported is 100 Megabytes and the maximum number of records supported is 1 million.

See section 2.6 “HTTP Headers” above for more details on file types supported and the HTTP request

and response headers that are set for file processing.

Not yet implemented

HTTP Method POST

Endpoint /products

Resource

Action /file

Parameters HTTP URL

Parameters Body

Request Payload .XLSX Excel file in OpenXML format containing Product[].

Response Payload Status[] containing the registration status of each individual record – either

success or failure



4.2.9 Batch Add Products

POST /products/batch/add

This API provides the capability to perform a batch create products to the Data Store, containing multiple products records in JSON format in the response body.

See Section 2.9 “Batch Processing” above for detailed information on processing batch requests.

HTTP Method POST

Endpoint /products/batch

Resource

Action /add

Parameters HTTP URL

Parameters Body


Response Payload Status[] containing the registration status of each individual record – either

success or failure of the operation requested.

Request Example

POST /gs1-pds/api/v1/products/batch/add HTTP/1.1

Host: cloud.gs1.org




[

{

"gtin": 09504000059231,


"brand": "GS1",



"gpc": 10000927,




},

{

"gtin": "09506000036809",




},

{

"gtin": "09506000036816",




},

]

Response Example

HTTP/1.1 200 OK


[







]

4.2.10 Batch Modify Products

POST /products/batch/modify

This API provides the capability to perform a batch modify (update) to products in the Data Store, containing multiple products records in JSON format in the response body.


HTTP Method POST


Resource

Action /modify

Parameters HTTP URL

Parameters Body


Response Payload Status[] containing the modify status of each individual record – either success

or failure of the operation requested.

Request Example

POST /gs1-pds/api/v1/products/batch/modify HTTP/1.1

Host: cloud.gs1.org




[

{

"gtin": 09504000059231,


"brand": "GS1",



"gpc": 10000927,




},

{

"gtin": "09506000036809",




},

{

"gtin": "09506000036816",




},

]

Response Example

HTTP/1.1 200 OK




[





]

4.2.11 Batch Delete Products

POST /products/batch/delete

This API provides the capability to request deletion of a batch of products in the Data Store. This method can be used to delete existing products.


HTTP Method POST


Resource

Action /delete

Parameters HTTP URL

Parameters Body


Response Payload Status[] containing the deletion status of each individual record – either success

or failure of the operation requested. If a product does not exist, the system does

not consider that to be an error condition and a status code of ‘4’ will be returned.

Request Example

POST /gs1-pds/api/v1/products/batch/delete HTTP/1.1

Host: cloud.gs1.org




[

{

"gtin" : "21214392873019",

"targetMarket" : "834"

},

{

"gtin" : "67451106546056",

"targetMarket" : "834"

}

]

Response Example

HTTP/1.1 200 OK


[

{

"gtin": "21214392873019",


"status": 4

},

{

"gtin": "67451106546056",


"status": 4

}



]

4.2.12 Batch Refresh Products

POST /products/batch/refresh

This API provides the capability to request refresh of a batch of products in the Data Store. This API call refreshes the product last updated timestamp in the Data Store with the current time. In effect, it explicitly confirms that the existing product data is fresh. The API returns the last updated date time

for the batch of products, which is the timestamp when the batch was refreshed. The timestamp

information SHALL be returned in the Last-Modified response header, and only applies to products

that were successfully refreshed. If all products in the batch failed to refresh, no Last-Modified response

header will be returned.


HTTP Method POST


Resource

Action /refresh

Parameters HTTP URL

Parameters Body


Response Payload Status[] containing the refresh status of each individual record – either success

or failure of the operation requested.

Request Example

POST /gs1-pds/api/v1/products/batch/refresh HTTP/1.1

Host: cloud.gs1.org




[

{

"gtin": 09504000059231,


},

{

"gtin": "09506000036809",


},

{

"gtin": "09506000036816",


},

]

Response Example

HTTP/1.1 200 OK

Last-Modified: Thu, 07 Dec 2017 21:44:17 GMT


[

{"gtin":09504000059231,"targetMarket":"056","reason":[ ],"status":3},




]



4.3 Open API Specification

Open API (formerly known as Swagger) is a specification that allows you to layout, describe and document an API. It is built around JSON to specify API metadata, structure and data models. This

results in a language agnostic and machine-readable interface that allows both humans and machines to smoothly understand the capabilities of a restful service. Since version 2.0, the YAML format support has been introduced which makes it even more human readable. However, the current version 2.0 of the Open API specification has been found to be inadequate in describing rich APIs like this one. The next version 3 of the Open API specification will likely be released before the end of 2017 and will address the current shortcomings making it usable and ready for mass

adoption.

A subsequent release of this specification may include an Open API 3.0 API specification of the Data Store API, in YAML format. A beautiful and elegant web / HTML render of this specification may also be made available online.

https://www.openapis.org/

gs1 data store api · pdf filecameron green senior director, b2c, industry solutions, gs1...

Documents