Session based API# #
Many methods in this API require authentication, some are available without. But in any case, a session should be maintained from the beginning to the end, using standard web techniques, preferably using cookies. Any Interaction follows the pattern logon()->doSomething()->logout(). Again, even if no authentication is required, the session should be maintained for tracability and for internal performance optimizations.
A Session can be maintained using standard cookies (for HTTP Headers), or by handing over the sessionid in a parameter x-oekobox-sid. The login call provides the session id in its repsonse too.
In order to enforce a valid session check, one may add a parameter oo-auth or a request header x-oo-auth to the request (its value is meaningless). If this parameter or header exists, any API call returns HTTP 401 if the underlaying session is not authenticated.
Initial Binding# #
Any client is „bound“ to a specific shop instance and to a specific account in that instance. The process to connect a client with such an account is called binding. It involves the shop selection, and the input of username and password. These parameters should be cached (indefinitely) on the client side, to give a feeling of instantly being connected. This mechanism allows to distribute one client that can be adjusted for several sites at Ökobox-Online with minimal configuration. See Bind-request for more details.
You dont need this, if you are coding for one specific shop instance only.
Common minimized REST/JSON-based Request-Response syntax# #
All data is returned as JSON structure that typically hold only the type and value information. The property names of the objects can be found in this documentation. See API.concepts.DataLists. From a certain size on, responses will be gzip-compressed (if supported by the caller).
Optional authentication via Basic Auth# #
A normal authentication is using a logon-step. For some methods, it is possible to avoid this by using HTTP Basic Auth instead to save this one network roundtrip. See more on Authentication here
Business Logic# #
You may implement business logic based on the low level API calls. This section explains various Use Cases and Logic, that is typically required for a full featured online shop.