52eSELLER V3 API methods may return a variety of headers. The following article documents the state headers returned by V3 API methods.

State headers

Context may affect how some V3 API methods behave, in terms of what data is returned. For example:

• Defining language context in the request means that localized data (e.g. product name) is returned in the specified language.
• Defining currency context in the request means that prices are returned in the specified currency.

Since the nature of a REST API presupposes that the client includes all relevant information in the request itself, it is necessary for the client to “know” what state information applies for a resource and thus is appropriate.

For instance, when authenticating as a customer, it is relevant for the client to know what language/currency is specified for that customer (if any) so that the application may use that specific context information in subsequent request and thus display information such as product lists in the appropriate language/currency.

52eSELLER V3 API methods provides this information via so-called state headers, that are returned (as headers) by some API methods. In the API reference documentation, it is stated if an API method returns state headers.

V3 API methods may return the following state headers:

• X-Set-LangId
• X-Set-CounId
• X-Set-CurrId
• X-Set-LocId
• X-Set-PriceListId
• X-Set-PriceCalculationDate
• X-Set-InventoryCheck
• X-Set-CustomerId
• X-Set-SalesPersonId
• X-Set-VisitorId
• X-Set-Ticket – This is also an authentication header
• X-Set-Authentication – This is also an authentication header

The X-Set- prefix signals that the client may “do” something with the information – i.e. change the state of the resource or client if the state of the resource differs from the state of the client. This however also depends on the “usage” and “priority” of the state header, which is explained further in the following.

Some API methods may return only a subset (or none) of these headers.

State headers return values in the following format:

X-Set-{param}: {value};{usage}/{priority}

• Param LocId, LangId, CurrId, CounId, PriceCalculationDate, CustomerId, SalesPersonId, VisitorId, InventoryCheck, PriceListId. These are the parameters that may make up the state of the requested resource.
• Value The value of the header, e.g. language ID.
• Usage Communicates how to use the state information in subsequent requests. Possible values are “header”, “uriquery”, “implicit”.
  • Header means that the state information must be provided as a header in subsequent requests.
  • Uriquery means that the state information must be provided as a query parameter in subsequent requests (e.g. ?LangId=2&CurrId=54)
  • Implicit means that the state information is imbedded in an authentication header (“X-Set-Authentication” or “X-Set-Ticket”) and hence cannot be set. The only purpose of it is to provide information – it should be ignored by the client.
• Priority Communicates whether it is possible to change the state of the resource from API. Possible values are “informational”, “forced”.
  • Forced means that the state of the resource cannot be changed from API.
  • Informational means that state of the resource may be updated from API.
  There is currently no real application of “forced”, but in the future it may be possible to force a customer/login to use a specific currency/language/country/location/etc.

Examples of state headers

X-Set-LangId: 1;uriquery/informational
X-Set-CustomerId: 4201965;implicit/forced

Even though some API methods are context-agnostic, we strongly recommend setting all context parameters (for state information that is not “implicit”) in all API requests, as this ensures consistent behavior. It is up to the client to implement proper business logic to ensure a natural flow of state.

Basket state

Basket state cannot be altered by setting context parameters, since changing basket state involves many processes including recalculating prices and re-evaluating product eligibility.

Basket state (e.g. currency) must be updated using the appropriate API method

PUT /services/v3/baskets/{basketId}/state

NOTE that although country is considered part of state, it cannot be updated using the above API method. Since country is a property of the basket sellto/shipto address, it must be updated using the appropriate API method:

PUT /services/v3/baskets/{basketId}/sellto
PUT /services/v3/baskets/{basketId}/shipto

Authentication headers

Authentication headers are a sub-set of state headers in the sense that they return information about the authenticated user which naturally also influences state and thus what data is returned by the API. For instance, specific prices or product scope may be apply for specific authenticated users.

V3 API methods may return two types of authentication headers: X-Set-Authentication and X-Set-Ticket. The authentication headers have different applications described below.

• X-Set-Authentication

  Is used by API methods that require or allow this header. This includes (but is not limited to) the baskets, favorites and orders API methods. In the API reference documentation, it is clearly stated whether an API method allows or requires sending the Authentication header. Sending the Authentication header using methods that do not allow it, will result in an error response.

  Receiving the header

  X-Set-Authentication: GbT2iMwsNzIBJTZX8egqU2VeauDYRcsZeL34HSObq20/wBTJM1hbvNMkCzQtGF43;header/forced

  means that the client should send the header

  X-Authentication: GbT2iMwsNzIBJTZX8egqU2VeauDYRcsZeL34HSObq20/wBTJM1hbvNMkCzQtGF43

  in subsequent request (for methods that allow the header).

• X-Set-Ticket

  Is mainly used by products and menus API methods. We strongly recommend sending this header in any API request as it constitutes part of state and may influence what data is returned by the API.

  Receiving the header

  X-Set-Ticket: SKs5zIHxUPOghUxku/iafHQNFLUwqey0DB8kN1W1RVlB9USztPKrI0gwHzvDo/rY;header/forced

  means that the client should send the header

  X-Ticket: SKs5zIHxUPOghUxku/iafHQNFLUwqey0DB8kN1W1RVlB9USztPKrI0gwHzvDo/rY

  in subsequent requests.