OCAPI Metadata

The Open Commerce API provides data about itself (metadata). You can obtain API metadata by accessing an own API, the meta API. This API can be accessed like the shop and the data API, but with version 1 as API version. The meta API provides information about

To access the Meta API, you have to send an Authorization: Bearer OAuth token with every request, which is obtained via Account Manager. With the client ID, used to create the access token, the access to all resources via OCAPI settings is proofed and only the available resources and documents are shown. The results may differ, depending on the context used to access the metadata. In the context of a specific site, the OCAPI settings of the site are used to check the access rights for the requesting client and show him only the resources he’s allowed to access. The same applies to accessing the metadata in a global context, where the global OCAPI settings are used to retrieve only the metadata the client is allowed to access.

The Meta API responses are cached in the page cache for 24 hours. This means that the cache for the metadata is automatically cleared with page cache clearing.

List of APIs

The following example lists which APIs are available:

1REQUEST:
2GET /dw/meta/v1/rest HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6
7RESPONSE:
8HTTP/1.1 200 OK
9Content-Type: application/json;charset=UTF-8
10Cache-Control: max-age=900,must-revalidate
11Content-Length: 741
12{
13    "apis": [
14    {
15        "link": "https://example.com/s/-/dw/meta/v1/rest/data",
16        "name": "data"
17    },
18    {
19        "link": "https://example.com/s/-/dw/meta/v1/rest/meta",
20        "name": "meta"
21    },
22    {
23        "link": "https://example.com/s/-/dw/meta/v1/rest/shop",
24        "name": "shop"
25    }]
26}

List of Versions

The following example lists which API versions are available:

1REQUEST:
2GET /dw/meta/v1/rest/data HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6
7RESPONSE:
8HTTP/1.1 200 OK
9Content-Type: application/json;charset=UTF-8
10Cache-Control: max-age=900,must-revalidate
11Content-Length: 741
12{
13    "versions": [
14    {
15        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_2",
16        "name": "14.2",
17        "status": "deprecated"
18    },
19    {
20        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_6",
21        "name": "14.6",
22        "status": "deprecated"
23    },
24    ...
25    {
26        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1",
27        "name": "24.5",
28        "status": "current"
29    }
30    ]
31}

List of Resource Descriptions

The retrieved document is for using with swagger in version 2.0 and lists all resource paths with their input-parameters and return type descriptions. The following example lists supported resource URIs:

1REQUEST:
2GET /dw/meta/v1/rest/data/v23_1 HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6x-dw-pretty-print: true
7
8RESPONSE:
9HTTP/1.1 200 OK
10Content-Type: application/json;charset=UTF-8
11Cache-Control: max-age=900,must-revalidate
12Content-Length: 5981
13{
14    "info":
15    {
16        "version": "24.5",
17        "title": "Data API"
18    },
19    "swagger": "2.0",
20    "basePath": "https://example.com/s/-/dw/data/v23_1",
21    "paths":
22    {
23        "/customer_search":
24        {
25            "post":
26            {
27                "operationId": "customerSearchcustomer_search",
28                "responses":
29                {
30                    "default":
31                    {
32                        "schema":
33                        {
34                            "$ref": "#/definitions/customer_search_result"
35                        }
36                    }
37                },
38                "tags": [
39                    "customer_search"
40                ],
41                "parameters": [
42                {
43                    "in": "body",
44                    "required": true,
45                    "schema":
46                    {
47                        "$ref": "#/definitions/customer_search_request"
48                    },
49                    "name": "body"
50                }]
51            }
52        },
53        ...
54    },
55    "definitions":
56    {
57        ...,
58        "customer_search_result":
59        {
60            "properties":
61            {
62                "count":
63                {
64                    "format": "int32",
65                    "type": "integer"
66                },
67                "hits":
68                {
69                    "items":
70                    {
71                        "$ref": "customer_search_hit"
72                    },
73                    "type": "array"
74                },
75                ...
76            },
77            "id": "customer_search_result"
78        },
79        ...
80    }
81}

List of Documents

The following example lists all available documents for an API in a specific version:

1REQUEST:
2GET /dw/meta/v1/rest/data/v23_1/documents HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6x-dw-pretty-print: true
7
8RESPONSE:
9HTTP/1.1 200 OK
10Content-Type: application/json;charset=UTF-8
11Cache-Control: max-age=900,must-revalidate
12Content-Length: 741
13{
14    "data": [
15    {
16        "id": "credentials",
17        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/credentials"
18    },
19    {
20        "id": "customer",
21        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer"
22    },
23    {
24        "id": "customer_address",
25        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer_address"
26    },
27    ...]
28}

Show Document Information

The following example shows the metadata for a requested document for an API in a specific version:

1REQUEST:
2GET /dw/meta/v1/rest/data/v23_1/documents/customer_address_result HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6x-dw-pretty-print: true
7
8RESPONSE:
9HTTP/1.1 200 OK
10Content-Type: application/json;charset=UTF-8
11Cache-Control: max-age=900,must-revalidate
12Content-Length: 741
13{
14    "properties":
15    {
16        "count":
17        {
18            "format": "int32",
19            "type": "integer"
20        },
21        "data":
22        {
23            "items":
24            {
25                "$ref": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer_address"
26            },
27            "type": "array"
28        },
29        "next":
30        {
31            "type": "string"
32        },
33        ...
34    }
35}

Also it’s possible to include the child document definitions by adding a query parameter children=embedded:

1REQUEST:
2GET /dw/meta/v1/rest/data/v23_1/documents/customer_address_result?children=embedded HTTP/1.1
3Host: example.com
4Accept: application/json
5Authorization: Bearer <access_token>
6
7RESPONSE:
8HTTP/1.1 200 OK
9Content-Type: application/json;charset=UTF-8
10Cache-Control: max-age=900,must-revalidate
11Content-Length: 741
12{
13    "properties":
14    {
15        "count":
16        {
17            "format": "int32",
18            "type": "integer"
19        },
20        "data":
21        {
22            "items":
23            {
24                "customer_address":
25                {
26                    "required": [
27                        "address_id",
28                        "country_code",
29                        "last_name"
30                    ],
31                    "properties":
32                    {
33                        "address1":
34                        {
35                            "maxLength": 256,
36                            "type": "string"
37                        },
38                        ...
39                    }
40                }
41            },
42            "type": "array"
43        },
44        ...
45    },
46    "id": "customer_address_result"
47}

Attention!

The Open Commerce API (OCAPI) is now deprecated. The provisions described in our versioning and deprecation policy fully apply. For all new projects and major refactoring work, use B2C Commerce API (SCAPI) as the default REST API. For additional details, refer to Why Use SCAPI Instead of OCAPI.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!