Calling Norce Commerce Query
Norce Commerce Query is an API based on OData V4. It is an API to fill the need for solutions integrated with Norce that need to fetch data from Norce's data layer directly.
Norce Commerce Query API Reference
You can find the reference documentation here.
Code examples
See our Postman collection with query examples here:
Read about how to use the postman examples.
Communication protocols
Norce Commerce Query uses ODdata v4 over REST.
Authentication and authorization
Norce Commerce Query uses OAuth2 for authentication. The credentials is created in the Admin UI, see Accessing API's with OAuth2 accounts for more information.
HTTPS is required for all calls to the API.
Status codes
The Norce Commerce Query uses the standard HTTP status codes.
Restrictions
Norce Commerce Query is read only, the functionality in the OData standard for writing data is disabled.
Components and tools
The OData standard is REST-ish and can be accessed directly from any browser or from code.
There are a number of different client-side components that you can use to access data from code for all possible environments and programming languages. We ourselves use internally Simple.OData.Client. Just google “OData client <language/environment>” to find something.
Namespaces
Norce Commerce Query has it's methods divided into different namespaces.
| Namespace | Description | Cacheable |
|---|---|---|
| Core | Core data in Norce Commerce. This is master lists that is the same for all clients (tenants), like lists of Countries, Currencies, VatCodes, SalesAreas etc. |
Cache for a longer time. |
| Application | Application-specific data that does not belong directly in any of the other namespaces. This is client and application specific master lists, for example suppliers, parametrics, categories, etc. |
Cache for a longer time. |
| Customers | Customers, companies and account management in Norce Commerce. | Cache for a while. |
| Products | Product, supplier products, prices, onhand information etc. | Cache for a while. |
| Orders | Orders, Baskets (Quotations), Invoices, Delivery notes etc. | Cache for a while. |
| Reporting | Data prepared for handling different types of reports. Sales information, and some legacy system reports. | Cache for a while. |
| Shopping | Planned recurring orders and delivery methods. | Short cache time. |
Common practices
Avoid lookups on every row
(Called the N+1 query problem) Fetch the lookup data as one larger list, and lookup information in memory for every item.
Use simple lookups
(Avoid complex joins) Since Norce Commerce Query lets solutions query directly to the Norce data layer the design and recommended practice is to avoid complex queries and instead split them up in several queries.
If, for example, the requirement is to get the name of the pricelist from the order item, you firstly fetch the orderrow and get the pricelist id. Next you lookup the pricelists from this id. Combine this with the next best practice (below) and keep the pricelists cached in memory to get good performance.
Use a longer Cache time
(Where it's appropriate)
The recommended practice when using Norce Commerce Query is to have a smart caching strategy. Make sure to cache data from Application and Core namespace fairly long, since it will not change that often.
Postman examples
There are some good examples to try out, here.
Read about how to use out postman examples.