Upload
ngodien
View
260
Download
3
Embed Size (px)
Citation preview
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 2 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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 3 of 33
Version Date of Change Changed By Summary of Change
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 4 of 33
Version Date of Change Changed By Summary of Change
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’.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 5 of 33
Version Date of Change Changed By Summary of Change
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 6 of 33
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 7 of 33
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 8 of 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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 9 of 33
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].
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 10 of 33
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 11 of 33
■ 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;
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 12 of 33
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”
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 13 of 33
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].
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 14 of 33
Property Name Value / Type
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)
Property Name Value / Type
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 15 of 33
Property Name Value / Type
Required/Optional Description
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 16 of 33
Property Name Value / Type
Required/Optional Description
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:
Property Name Value / Type
Required/Optional Description
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:
Property Name Value / Type
Required/Optional Description
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 17 of 33
Property Name Value / Type
Required/Optional Description
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
Content-Type: application/json
WWW-Authenticate: Basic realm="GS1 Cloud"
{"exception":6,"message":"Invalid API key"}
HTTP/1.1 403 Forbidden
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 18 of 33
Content-Type: application/json
{"exception":4,"message":"Operation not permitted"}
HTTP/1.1 404 Not Found
Content-Type: application/json
{"exception":1,"message":"Missing parameter: Target Market"}
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{"exception":5,"message":"Cannot process request at this time"}
HTTP/1.1 501 Not Implemented
Content-Type: application/json
{"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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 19 of 33
Method API HTTP Method
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 20 of 33
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.
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 21 of 33
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 22 of 33
Request Payload
Response Payload HAL with Product[]
See section 2.8 Pagination for details on HAL.
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
"_embedded" : [ {
"gtin" : "00000065045497",
"targetMarket" : "834",
"brand" : "test brand",
"languageCode" : "en",
"labelDescription" : "description",
"gpc" : "gpc",
"companyName" : "company",
"informationProviderGln" : "1295170330647",
"imageUrlMedium" : "medium image url"
}, {
"gtin" : "00000085059801",
"targetMarket" : "834",
"brand" : "test brand",
"languageCode" : "en",
"labelDescription" : "description",
"gpc" : "gpc",
"companyName" : "company",
"informationProviderGln" : "3592522551117",
"imageUrlMedium" : "medium image url"
}, {
"gtin" : "00000072418482",
"targetMarket" : "834",
"brand" : "test brand",
"languageCode" : "en",
"labelDescription" : "description",
"gpc" : "gpc",
"companyName" : "company",
"informationProviderGln" : "5941809428518",
"imageUrlMedium" : "medium image url"
}, {
"gtin" : "00000023607798",
"targetMarket" : "834",
"brand" : "test brand",
"languageCode" : "en",
"labelDescription" : "description",
"gpc" : "gpc",
"companyName" : "company",
"informationProviderGln" : "4275116751450",
"imageUrlMedium" : "medium image url"
}, {
"gtin" : "00000073739913",
"targetMarket" : "834",
"brand" : "test brand",
"languageCode" : "en",
"labelDescription" : "description",
"gpc" : "gpc",
"companyName" : "company",
"informationProviderGln" : "5188834813913",
"imageUrlMedium" : "medium image url"
} ],
"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",
"href" : "https://localhost:8443/gs1-pds/api/v1/products?page=399&size=5"
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 23 of 33
}, {
"rel" : "self",
"href" : "https://localhost:8443/gs1-pds/api/v1/products?page=400&size=5"
}, {
"rel" : "next",
"href" : "https://localhost:8443/gs1-pds/api/v1/products?page=401&size=5"
}, {
"rel" : "last",
"href" : "https://localhost:8443/gs1-pds/api/v1/products?page=971&size=5"
} ]
}
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
Resource /{gtin}/{targetMarket}
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’:
Method API HTTP Method
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 24 of 33
Method API HTTP Method
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 25 of 33
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
Resource /{gtin}/{targetMarket}
Action
Parameters HTTP URL
Parameters Body
Request Payload Product
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
appropriate error information.
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
Resource /{gtin}/{targetMarket}
Action
Parameters HTTP URL
Parameters Body
Request Payload Product
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
appropriate error information.
4.2.4 Delete Product
DELETE /products/{gtin}/{targetMarket}
This API deletes a single product from the Data Store.
HTTP Method DELETE
Endpoint /products
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 26 of 33
Resource /{gtin}/{targetMarket}
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
Resource /{gtin}/{targetMarket}
Action /refresh
Parameters HTTP URL
Parameters Body
Request Payload
Response Payload If the product record does not exist or if the user does not have authorization to
delete the product record, then an Exception is returned containing the
appropriate error information.
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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 27 of 33
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
Content-Type: application/json
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",
"targetMarket": "840",
"labelDescription": "GS1 Test Product 1",
"imageUrlMedium": "www.example.com/test1.jpg"
},
{
"gtin": "09506000036816",
"targetMarket": "040"
"labelDescription": "GS1 Test Product 2",
"imageUrlMedium": "www.example.com/test2.jpg"
},
]
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 28 of 33
[
{"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
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 29 of 33
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
Request Payload Product[]multiple products in JSON
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
Content-Type: application/json
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",
"targetMarket": "840",
"labelDescription": "GS1 Test Product 1",
"imageUrlMedium": "www.example.com/test1.jpg"
},
{
"gtin": "09506000036816",
"targetMarket": "040"
"labelDescription": "GS1 Test Product 2",
"imageUrlMedium": "www.example.com/test2.jpg"
},
]
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
{"gtin":09504000059231,"targetMarket":"056","status":1},
{"gtin":"09506000036809","targetMarket":"840","status":2},
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 30 of 33
{"gtin":"09506000036816","targetMarket":"040","status":5,"reason":"Operation not
permitted. Not authorized."}
]
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.
See Section 2.9 “Batch Processing” above for detailed information on processing batch requests.
HTTP Method POST
Endpoint /products/batch
Resource
Action /modify
Parameters HTTP URL
Parameters Body
Request Payload Product[]multiple products in JSON
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
Content-Type: application/json
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",
"targetMarket": "840",
"labelDescription": "GS1 Test Product 1",
"imageUrlMedium": "www.example.com/test1.jpg"
},
{
"gtin": "09506000036816",
"targetMarket": "040"
"labelDescription": "GS1 Test Product 2",
"imageUrlMedium": "www.example.com/test2.jpg"
},
]
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 31 of 33
[
{"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.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.
See Section 2.9 “Batch Processing” above for detailed information on processing batch requests.
HTTP Method POST
Endpoint /products/batch
Resource
Action /delete
Parameters HTTP URL
Parameters Body
Request Payload Product[]multiple products in JSON
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
Content-Type: application/json
Accept: application/json
Authorization: Basic aHR0cHdhdGNoXcfft54jYtGG7h02TiQzOmY=
[
{
"gtin" : "21214392873019",
"targetMarket" : "834"
},
{
"gtin" : "67451106546056",
"targetMarket" : "834"
}
]
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"gtin": "21214392873019",
"targetMarket": "834",
"status": 4
},
{
"gtin": "67451106546056",
"targetMarket": "834",
"status": 4
}
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 32 of 33
]
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.
See Section 2.9 “Batch Processing” above for detailed information on processing batch requests.
HTTP Method POST
Endpoint /products/batch
Resource
Action /refresh
Parameters HTTP URL
Parameters Body
Request Payload Product[]multiple products in JSON
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
Content-Type: application/json
Accept: application/json
Authorization: Basic aHR0cHdhdGNoXcfft54jYtGG7h02TiQzOmY=
[
{
"gtin": 09504000059231,
"targetMarket": "056",
},
{
"gtin": "09506000036809",
"targetMarket": "840",
},
{
"gtin": "09506000036816",
"targetMarket": "040"
},
]
Response Example
HTTP/1.1 200 OK
Last-Modified: Thu, 07 Dec 2017 21:44:17 GMT
Content-Type: application/json
[
{"gtin":09504000059231,"targetMarket":"056","reason":[ ],"status":3},
{"gtin":"09506000036809","targetMarket":"840","status":3},
{"gtin":"09506000036816","targetMarket":"040","status":5,"reason":"Operation not
permitted. Not authorized."}
]
GS1 Cloud Phase 1 - Data Store API
Release 0.8.3, DRAFT, December 9, 2017 © 2017 GS1 AISBL Page 33 of 33
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.