Use the API
How to use our low level API to access data from the PCG Warehouse.
There is also a javascript toolkit that encapsulates most logic and calls.
REST-Like but not REST
- We typically access parameters as GET or POST and rarely implemented PUT/DELETE/UPDATE. Instead, we typically have /new, /list /update or /delete method endpoints that take the appropriate parameters.
- General Philosophy: Our API has methods (aka endpoints) that (typically) generate lists of JSON response objects. These objects are intentionally rather simple entities without a deep nesting. Similar to a database schema , they relate to each other, usually with Id's. You typically get all required response types for the task, that the endpoint name implies (e.g. getting items provides you with the proper alternative units as well).
- You may get the response in different formats (from compact to elaborated json)
- Versioning: a new version increases the postfix integer, so /api/user26 becomes /api/user27. Similar the Response Objects. A new version is a new class with the postfix number increased. The highest number is always the most recent version.
endpoint URLS
The endpoint path's contains the name of the addressed backend , e.g. "schoenegge" in this example:
https://oekobox-online.de/v3/shop/schoenegge/api/items21?categoryid=0&max=2
The base url (up to /api) is provided upon request, or better, trough a lookup using this directory call
https://oekobox-online.eu/v3/bind5/schoenegge?oo-rf=json
with this response:
"shopurls": [
{
"displayName": "Naturgarten Schönegge",
"webDomain": "http://oekobox-online.de/v3/shop/schoenegge",
"secureWebDomain": "https://oekobox-online.de/v3/shop/schoenegge",
"homeUrl": "https://schoenegge.shop",
"hasLogo": "https://schoenegge.shop/images/logo_schoenegge.png",
"sysName": "schoenegge",
"isTest": 0,
"lat": 48.52065507026649,
"lng": 11.765992641448975,
...
}
]
}
secureWebDomain represents the base path.
You need to be given the system name.
possible response formats
The output can be controlled by a parameter oo-rf:
| oo-rf | legacy equivalent | result |
|---|---|---|
| compact | response-format=compact | compact format without any schema info (application/json) |
| compacts | response-format=compact & schema=include | compact format, but with schema (application/json) |
| full | response-format=full | key value exist in all records (application/json) |
| fulls | response-format=full & schema=include | key value exist in all records, schema added (application/json) |
| json | response-format=json | pure json response, key fields exist (application/json) |
| md | schema=md | Documentation: markdown for human consumption (text/markdown) |
| html | -new- | Documentation: same content as md, rendered as styled HTML page (text/html) |
| js | schema=js | javascript code to parse a compact response (application/javascript) |
| openapi | schema=openapi | openAPI description for the json call option (text/yaml) |
| yaml | schema=openapi | same as openapi (alias) (text/yaml) |
(The oo-rf parameter replaces the legacy response-format + schema pair. When oo-rf is present it takes precedence; the old parameters still work for backwards compatibility.)
Use the documentation format md or html to explore an endpoint.
we are session based
Most calls benefit from a session frame: it starts with a /api/logon call and ends with a /api/logout. A session gets a 1h timeout after logon.
Sessions are used without an explicit logon as well, but getting a timeout of 4 Minutes only.
The session can be transferred using a cookie named OO-SESSION , alternatively also by http request header X-oekobox-sid or a request parameter x-oekobox-sid
force authentication
Historically, there are no permission error responses: if specific permissions where not granted, just no data was returned.
Using the paramaeter oo-auth as parameter (or x-oo-auth as request header), this behaviour changes: a proper 4XX Error Response is given in HTTP calls.
(yaml descriptions include that parameter in the documentation)
Permissions are granted in the backend system. Generally, all data that is public in the online shops do not need extra permissions.
access restrictions
API usage is monitored. Developers should request an API key, that provider higher bandwith and rate limits. A APi Key can be valid for a specific tenant or for all tenants. Contact us to request one.
getting started
- You need the system name, e.g.
schoenegge - obtain the base URL as explained above
- issue your fist API call, e.g. the mentioned call for special offer items as shown above
Next steps:
- Add a logon/logout to the example. Once logged on, you see prices and offering as well as orders for the given client. The logon responds with a series of ShopDate objects, that gives first pointers to available delivery dates or existing orders.
- Obtain an API key for further development.
- Browse through the skills list to get impressions on what you can do with the API.
images and files
API objects only tell you that an image exists (thumbnailCode, imageCode, image hashes); the
bytes come from the shop's image proxy (<base URL>/t.px?bs.i=<id> etc.), which also scales and
caches. See the file-proxy skill.