SYSTEM DESIGN
/
Frontend design
/
Using Norce Services
Last updated
Draft

This document is still a draft and might change

Using Norce Commerce Services

The Norce Commerce Services is a collection of microservices that utilizes REST to provide functionality to an eCommerce application that utilizing Norce Commerce as the base platform.

Documentation

You can find the reference documentation here.

Environments

Norce provides several environments and has also older environments still in use for Norce [Storm].

See more about environments here.

Production

  • [clientname].api-[region].norce.tech/commerce/[servicename>/[version]
    (for example: mycompany.api-se.norce.tech/commerce/product/1.1)
  • api.storm.io/stormapi/1.1 or api.storm.io/api/1.1 for Norce [Storm] hosting on Iver
  • [clientname].storm.io/stormapi/1.1 or [clientname].storm.io/api/1.1 for Norce [Storm] hosting on Azure

Playground

Runs same versions as the production environment. But are built for experimentation and development purposes.

Only provided for Norce Commerce.

[clientname].api-[region].playground.norce.tech/commerce/[servicename>/[version]
(for example: demo.api-se.playground.norce.tech/commerce/product/1.1)

Stage

Runs same versions as the production environment. Built for handle as close as real tests for a client in production.

[clientname].api-[region].stage.norce.tech/commerce/[servicename>/[version]
(for example: mycompany.api-se.stage.norce.tech/commerce/product/1.1)

Old environments

Lab (stage)

The lab environment is where the current or upcoming version of the code is running, and it is intended for development and experimentation purposes. To access this environment, use the hostname api.lab.storm.io.

Lab environments are no longer provided, use Playground or Staging instead.

Demo

The Demo environment is exclusively for running the Demo client, but it is open for testing and experimentation. To access this environment, use the hostname demo.storm.io.

Demo environment is replaced by an open playground environment

Additional environments

It is possible to create extra environments for a client by setting up a new client tenant. These environments can be utilized as parallel stage environments or for developing new features. However, keep in mind that additional environments generally come with extra costs.

Examples

See our postman collection with API examples here:

read about our postman examples here

Communication protocols

Norce only supports the REST protocol for Norce Commerce, but have SOAP supported in Norce [Storm] for backward compatibility purposes only.

Authentication and authorization

Norce Commerce Services uses OAuth2 for authentication. The credentials are created in the admin UI, see Accessing APIs with OAuth2 accounts for more information.

Note

Previously, the Norce [Storm] API utilized Client Certificates to authenticate API calls, but this feature has been disabled and is no longer in use. Old client certificates are no longer renewed.

Installation

To set up the OAuth2 access, see Accessing APIs with OAuth2 accounts for more information.

If you are using the client libraries provided in the open source, see the specific documentation for those here (GitHub).

Status codes and errors

The Norce Commerce Services uses the standard HTTP status codes. The Norce Commerce Services can return two types of status codes for errors:

  • "Internal Server Error" (500) and
  • "Bad Request" (400).

In the case of a bad request, additional information will also be provided in the response body.

Here is an example:

{
  "MessageId": 0,
  "Message": "The basket is missing. Try deleting the cookies for this site and try again.",
  "Orchestration": null,
  "TimeStamp": "/Date(1591968688391+0200)/",
  "Record": "<NameValues xmlns=\"Enferno.Services.Contracts.Expose\" xmlns:i=\"http://www.w3.org/2001/XMLSchema-instance\"&gt;&lt;Item&gt;&lt;Name&gt;QuotationMissing&lt;/Name&gt;&lt;Value>The basket is missing. Try deleting the cookies for this site and try again.</Value></Item></NameValues>",
  "Messages": [
    {
      "Key": "QuotationMissing",
      "Value": "The basket is missing. Try deleting the cookies for this site and try again."
    }
  ]
}

The error response contract has a Messages collection with items having Key and Value fields. See all the possible error messages here: ListErrorMessages

Client libraries

Read about the open source resources here.

Sample application

Read more about the sample storefront application here: The Sample Storefront project Here is the sample storefront application on GitHub

Suggested further reading

Previous page
Next page