NAME

ProductOpener::API - implementation of READ and WRITE APIs

DESCRIPTION

This module contains functions that are common to multiple types of API requests.

Specialized functions to process each type of API request is in separate modules like:

APIProductRead.pm : product READ APIProductWrite.pm : product WRITE

add_error ($response_ref, $error_ref, $status_code = 400)

Add an error to the response object.

Parameters

$status_code (input)

HTTP status code to return in the response, defaults to 400 bad request.

read_request_body ($request_ref)

API V3 POST / PUT / PATCH requests do not use CGI Multipart Form data, and instead pass a JSON structure in the body. This function reads the request body and saves it in $request_ref->{body}

It must be called before any call to CGI.pm param() which will read the body.

decode_json_request_body ($request_ref)

Decodes the JSON body of a request and store it in $request_ref->{request_body_json}

Errors are returned in $request_ref->{api_response}

determine_request_result ($response_ref)

Based on the response's errors and warnings, determine the overall status of the request.

add_localized_messages_to_api_response ($target_lc, $response_ref)

Functions that process API calls may add message ids in $request_ref->{api_response} to indicate the result and warnings and errors.

This functions adds English and/or localized messages for those messages.

API messages (result, warning and errors messages and impacts) are generated: - in English in the "name" field: those messages are intended for use by developers, monitoring systems etc. - in the language of the user in the "lc_name" field: those messages may be displayed directly to users (e.g. to explain that some field values are incorrect and were ignored)

$response_ref (input and output)

Reference to the response object.

send_api_response ($request_ref)

Send the API response with the right headers and status code.

Parameters

$request_ref (input)

Reference to the request object.

Return value

Reference to the customized product object.

process_api_request ($request_ref)

Process API v3 requests.

Parameters

$request_ref (input)

Reference to the request object.

normalize_requested_code($requested_code, $response_ref)

Normalize the product barcode requested by a READ or WRITE API request. Return a warning if the normalized code is different from the requested code.

Parameters

$request_code (input)

Reference to the request object.

$response_ref (output)

Reference to the response object.

Return value

Normalized code and, if available, GS1 AI data string.

get_images_to_update($product_ref, $target_lc)

Return a list of images that are too old, or that are missing. This is used to ask users to update images.

Parameters

$product_ref (input)

Reference to the product object

$target_lc (input)

Target language code

Return value

Reference to a hash of images that need to be updated. The keys are the image ids (e.g. front_fr), and the value is the age in seconds of the image (or 0 if we don't have an image yet)

customize_packagings ($request_ref, $product_ref)

Packaging components are stored in a compact form: only taxonomy ids for shape, material and recycling.

This function returns a richer structure with local names for the taxonomy entries.

Parameters

$request_ref (input)

Reference to the request object.

$product_ref (input)

Reference to the product object (retrieved from disk or from a MongoDB query)

Return value

Reference to the customized product object.

api_compatibility_for_field ($field, $api_version)

To support older API versions that can request fields that have been renamed or changed, we rename older requested fields to the new field names to construct the response.

Resulting fields will then be renamed back to older names by the api_compatibility_for_product function.

api_compatibility_for_product ($product_ref, $api_version)

The response schema can change between API versions. This function transforms the product object to match the requested API version.

customize_response_for_product ( $request_ref, $product_ref, $fields_comma_separated_list, $fields_ref )

Using the fields parameter, API product or search queries can request a specific set of fields to be returned.

This function filters the field to return only the requested fields, and computes requested fields that are not stored in the database but created on demand.

Parameters

$request_ref (input)

Reference to the request object.

$product_ref (input)

Reference to the product object (retrieved from disk or from a MongoDB query)

$fields_comma_separated_list (input)

Comma separated list of fields (usually from GET query parameters), default to none.

Special values: - none: no fields are returned - all: all fields are returned, and special fields (e.g. attributes, knowledge panels) are not computed - updated: fields that were updated by a WRITE request

$fields_ref (input)

Reference to a list of fields (alternative way to provide fields, e.g. from a JSON body).

Return value

Reference to the customized product object.

check_user_permission ($request_ref, $response_ref, $permission)

Check the user has a specific permission, before processing an API request. If the user does not have the permission, an error is added to the response.

Parameters

$request_ref (input)

Reference to the request object.

$response_ref (output)

Reference to the response object.

$permission (input)

Permission to check.

Return value $has_permission

1 if the user has the permission, 0 otherwise.