OCAPI metadata 19.8

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. Note that 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 is 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:

REQUEST:
GET /dw/meta/v1/rest HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "apis": [
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data",
        "name": "data"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/meta",
        "name": "meta"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/shop",
        "name": "shop"
    }]
}

List of versions

The following example lists which API versions are available:

REQUEST:
GET /dw/meta/v1/rest/data HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "versions": [
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_2",
        "name": "14.2",
        "status": "deprecated"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_6",
        "name": "14.6",
        "status": "deprecated"
    },
    ...
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_8",
        "name": "19.8",
        "status": "current"
    }
    ]
}

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:

REQUEST:
GET /dw/meta/v1/rest/data/v19_8 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 5981
{
    "info":
    {
        "version": "19.8",
        "title": "Data API"
    },
    "swagger": "2.0",
    "basePath": "https://example.com/s/-/dw/data/v19_8",
    "paths":
    {
        "/customer_search":
        {
            "post":
            {
                "operationId": "customerSearchcustomer_search",
                "responses":
                {
                    "default":
                    {
                        "schema":
                        {
                            "$ref": "#/definitions/customer_search_result"
                        }
                    }
                },
                "tags": [
                    "customer_search"
                ],
                "parameters": [
                {
                    "in": "body",
                    "required": true,
                    "schema":
                    {
                        "$ref": "#/definitions/customer_search_request"
                    },
                    "name": "body"
                }]
            }
        },
        ...
    },
    "definitions":
    {
        ...,
        "customer_search_result":
        {
            "properties":
            {
                "count":
                {
                    "format": "int32",
                    "type": "integer"
                },
                "hits":
                {
                    "items":
                    {
                        "$ref": "customer_search_hit"
                    },
                    "type": "array"
                },
                ...
            },
            "id": "customer_search_result"
        },
        ...
    }
}

List of documents

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

REQUEST:
GET /dw/meta/v1/rest/data/v19_8/documents HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "data": [
    {
        "id": "credentials",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_8/documents/credentials"
    },
    {
        "id": "customer",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_8/documents/customer"
    },
    {
        "id": "customer_address",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_8/documents/customer_address"
    },
    ...]
}

Show document information

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

REQUEST:
GET /dw/meta/v1/rest/data/v19_8/documents/customer_address_result HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "properties":
    {
        "count":
        {
            "format": "int32",
            "type": "integer"
        },
        "data":
        {
            "items":
            {
                "$ref": "https://example.com/s/-/dw/meta/v1/rest/data/v19_8/documents/customer_address"
            },
            "type": "array"
        },
        "next":
        {
            "type": "string"
        },
        ...
    }
}
    

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

REQUEST:
GET /dw/meta/v1/rest/data/v19_8/documents/customer_address_result?children=embedded HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "properties":
    {
        "count":
        {
            "format": "int32",
            "type": "integer"
        },
        "data":
        {
            "items":
            {
                "customer_address":
                {
                    "required": [
                        "address_id",
                        "country_code",
                        "last_name"
                    ],
                    "properties":
                    {
                        "address1":
                        {
                            "maxLength": 256,
                            "type": "string"
                        },
                        ...
                    }
                }
            },
            "type": "array"
        },
        ...
    },
    "id": "customer_address_result"
}