← API Index

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

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

Next steps:

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.