OCAPI metadata 19.3

The Open Commerce API provides data about itself — meta data. You can obtain API meta data 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 which is used to access the meta data. In the context of a specific site the Ocapi settings of this site are used to check the accessrights for the requesting client and show him only the resources which he is allowed to access. The same does apply for accessing the meta data in global context, where the global ocapi settings are used to retrieve only the resources meta data, 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 meta data 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_3",
        "name": "19.3",
        "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_3 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.3",
        "title": "Data API"
    },
    "swagger": "2.0",
    "basePath": "https://example.com/s/-/dw/data/v19_3",
    "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_3/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_3/documents/credentials"
    },
    {
        "id": "customer",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_3/documents/customer"
    },
    {
        "id": "customer_address",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v19_3/documents/customer_address"
    },
    ...]
}

Show document information

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

REQUEST:
GET /dw/meta/v1/rest/data/v19_3/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_3/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_3/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"
}